├── .gitignore ├── .readthedocs.yaml ├── LICENSE ├── Makefile ├── README.rst ├── env.yml ├── figures ├── CENSO │ ├── 2methyl1pentene_nmr.png │ ├── Dglucopyranose.png │ ├── censo_logo_300dpi.png │ ├── cis4hexen1ol.png │ ├── cis4hexen1ol_nmr.png │ ├── short_censo.png │ └── solvents.png ├── README ├── alagly.png ├── alaglyconfs.png ├── alaglydep.png ├── alaglyprot.png ├── benzene_dimer.png ├── bromochloroethane.gif ├── bromochloroethane.png ├── claisen.gif ├── claisen_conv.png ├── concertedscan.gif ├── confining_anisotropic.png ├── confining_misplaced.png ├── confining_shifted.png ├── constrain.gif ├── cre-pes.png ├── crest-mf.png ├── crest-v1.png ├── crest-v2i.png ├── crest_cuvaline.png ├── crest_overlay.png ├── crest_pt.png ├── crest_surface.png ├── crest_ts.png ├── cyclohexane.gif ├── cyclohexane_conv.png ├── diphenylacetylene.png ├── dipro.png ├── directed.png ├── docs.png ├── enso │ ├── enso-detailed.png │ ├── enso-procedure3.png │ ├── enso-short.png │ ├── enso_2-methly1pentene.png │ ├── enso_2methyl-1-pentene.png │ ├── enso_cis4hexen1ol.png │ ├── enso_get_spectrum.png │ ├── enso_spectrum_2-methyl-1-pentene.png │ └── structure.png ├── ethane.gif ├── ethane.png ├── fix.gif ├── gas.gif ├── gas_slow.gif ├── gbsa-infinity.gif ├── gbsa.gif ├── gfnff.jpg ├── h0tuning.png ├── imtd-smtd.png ├── mit.png ├── notconcertedscan.gif ├── ohne.png ├── oniom_23.png ├── optimize-benzyne-infinity.gif ├── optimize-benzyne.gif ├── optimize-cp-infinity.gif ├── optimize-cp.gif ├── optimize-ethyne-infinity.gif ├── optimize-ethyne.gif ├── path-ts.png ├── potential_shapes.png ├── ptb_cover_image.png ├── ptb_ir_spectra.png ├── ptb_raman_1edn.png ├── qcg-micro.png ├── qcg-supra.png ├── qcg_Fe.png ├── qcg_algo.png ├── qcg_bacillaene.png ├── qcg_solv_fe.png ├── qcg_wallpot.png ├── qcxms │ ├── QCxMS_EI-CID_Flowchart.png │ └── qcxms_logo.svg ├── qcxms2 │ ├── 2pentanone_gfn2.png │ └── qcxms2_logo.svg ├── spgfn.png ├── undirected.png ├── vimdiffstartend.png ├── wclust1.png ├── wclustpot.png ├── wrongclaisen.gif └── wrongclaisen_conv.png ├── logo ├── akgrimme_logo_final2018_xtbdocs.png └── logo_abtgrimme_desktop.png ├── make.bat ├── requirements.txt └── source ├── CENSO_docs ├── abbreviations.rst ├── censo.rst ├── censo_extensive_keywords.rst ├── censo_implementation.rst ├── censo_nmr.rst ├── censo_parallel.rst ├── censo_uvvis.rst └── censorc.rst ├── _posts ├── 2021 │ ├── dftbplus-version-21.2.rst │ ├── dftd4-version-3.2.0.rst │ ├── qcxms-version-5.0.3.rst │ ├── qcxms-version-5.1.0.rst │ ├── qcxms-version-5.1.2.rst │ └── xtb-version-6.4.1.rst └── 2022 │ └── xtb-version-6.5.0.rst ├── _static └── custom.css ├── basics.rst ├── capi.rst ├── commandline.rst ├── community ├── gaussian.rst ├── index.rst ├── pysisyphus.rst ├── pyvibms.rst └── scine.rst ├── conf.py ├── crestxmpl.rst ├── development.rst ├── dipro.rst ├── enso_doc ├── enso.rst ├── enso_anmr.rst ├── enso_setup.rst ├── enso_usage.rst └── plotting.rst ├── gbsa.rst ├── geometry.rst ├── gfnff.rst ├── gsm.rst ├── help.rst ├── hessian.rst ├── hidden_code_block.py ├── index.rst ├── license.rst ├── md.rst ├── mtd.rst ├── news.rst ├── oniom.rst ├── optimization.rst ├── path.rst ├── pcem.rst ├── periodic_boundary_conditions.rst ├── properties.rst ├── ptb.rst ├── python.rst ├── qcxms2_doc ├── qcxms2.rst ├── qcxms2_cites.rst ├── qcxms2_ex.rst ├── qcxms2_plot.rst ├── qcxms2_run.rst └── qcxms2_setup.rst ├── qcxms_doc ├── qcxms.rst ├── qcxms_cites.rst ├── qcxms_ex.rst ├── qcxms_plot.rst ├── qcxms_run.rst └── qcxms_setup.rst ├── requirements.txt ├── scan.rst ├── setup.rst ├── sp.rst ├── spgfn.rst ├── versions.rst ├── xcontrol.rst ├── xtb_docking.rst ├── xtb_info.rst ├── xtb_ir.rst ├── xtb_thermo.rst ├── xtb_topo.rst └── xtbrelatedrefs.rst /.gitignore: -------------------------------------------------------------------------------- 1 | /build*/ 2 | -------------------------------------------------------------------------------- /.readthedocs.yaml: -------------------------------------------------------------------------------- 1 | # .readthedocs.yaml 2 | # Read the Docs configuration file 3 | # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details 4 | 5 | # Required 6 | version: '2' 7 | 8 | # Set the version of Python and other tools you might need 9 | build: 10 | os: ubuntu-22.04 11 | tools: 12 | python: "3.9" 13 | 14 | # Build documentation in the docs/ directory with Sphinx 15 | sphinx: 16 | configuration: source/conf.py 17 | 18 | # We recommend specifying your dependencies to enable reproducible builds: 19 | # https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html 20 | python: 21 | install: 22 | - requirements: source/requirements.txt 23 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line. 5 | SPHINXOPTS = 6 | SPHINXBUILD = sphinx-build 7 | SOURCEDIR = source 8 | BUILDDIR = build 9 | 10 | # Put it first so that "make" without argument is like "make help". 11 | help: 12 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 13 | 14 | .PHONY: help Makefile 15 | 16 | # Catch-all target: route all unknown targets to Sphinx using the new 17 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 18 | %: Makefile 19 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 20 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | Documentation for xtb and related software 2 | ========================================== 3 | 4 | .. image:: https://readthedocs.org/projects/xtb-docs/badge/?version=latest 5 | :alt: Documentation Status 6 | :target: https://xtb-docs.readthedocs.io 7 | .. image:: https://img.shields.io/github/v/release/grimme-lab/xtb?label=xtb 8 | :alt: xtb release 9 | :target: https://github.com/grimme-lab/xtb/releases/latest 10 | .. image:: https://img.shields.io/github/v/release/crest-lab/crest?label=crest 11 | :alt: crest release 12 | :target: https://github.com/crest-lab/crest/releases/latest 13 | .. image:: https://img.shields.io/github/v/release/grimme-lab/enso?label=enso 14 | :alt: enso release 15 | :target: https://github.com/grimme-lab/enso/releases/latest 16 | .. image:: https://img.shields.io/github/v/release/grimme-lab/CENSO?label=CENSO 17 | :alt: CENSO release 18 | :target: https://github.com/grimme-lab/CENSO/releases/latest 19 | .. image:: https://img.shields.io/github/v/release/grimme-lab/QCxMS?label=QCxMS 20 | :alt: QCxMS release 21 | :target: https://github.com/qcxms/QCxMS/releases/latest 22 | .. image:: https://img.shields.io/github/v/release/grimme-lab/QCxMS2?label=QCxMS2 23 | :alt: QCxMS2 release 24 | :target: https://github.com/grimme-lab/QCxMS2/releases/latest 25 | 26 | This is the official documentation for the extended tight binding (xtb) program 27 | package and related or dependent methods, like the conformer-rotamer ensemble 28 | search tool (crest) and the energetic sorting of conformer rotamer ensembles (enso) 29 | program. 30 | 31 | Get the latest version of of the programs by clicking on the respective badge. 32 | 33 | This documentation is currently hosted at 34 | `readthedocs.org `_. 35 | 36 | Building this documentation 37 | --------------------------- 38 | 39 | This documentation is built with sphinx. 40 | 41 | You can easily setup sphinx with the provided conda environment file 42 | 43 | .. code:: 44 | 45 | conda env create -n sphinx -f env.yml 46 | conda activate sphinx 47 | 48 | 49 | Build the documentation by invoking 50 | 51 | .. code:: 52 | 53 | make html 54 | 55 | 56 | Contributors 57 | ------------ 58 | 59 | * Fabian Bohle 60 | * Markus Bursch 61 | * Eike Caldeweyher 62 | * Sebastian Dohm 63 | * Sebastian Ehlert 64 | * Johannes Gorges 65 | * Abylay Katbashev 66 | * Jeroen Koopman 67 | * Julia Kohn 68 | * Hagen Neugebauer 69 | * Christoph Plett 70 | * Philipp Pracht 71 | * Karola Schmitz 72 | * Sarah Schmitz 73 | * Jakob Seibert 74 | * Sebastian Spicher 75 | * Leopold Seidler 76 | * Marcel Müller 77 | -------------------------------------------------------------------------------- /env.yml: -------------------------------------------------------------------------------- 1 | name: sphinx-docs 2 | channels: 3 | - conda-forge 4 | dependencies: 5 | - python 6 | - sphinx 7 | - sphinx-design 8 | - sphinx-togglebutton 9 | - sphinx-copybutton 10 | - sphinx_rtd_theme 11 | - ablog 12 | -------------------------------------------------------------------------------- /figures/CENSO/2methyl1pentene_nmr.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/CENSO/2methyl1pentene_nmr.png -------------------------------------------------------------------------------- /figures/CENSO/Dglucopyranose.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/CENSO/Dglucopyranose.png -------------------------------------------------------------------------------- /figures/CENSO/censo_logo_300dpi.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/CENSO/censo_logo_300dpi.png -------------------------------------------------------------------------------- /figures/CENSO/cis4hexen1ol.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/CENSO/cis4hexen1ol.png -------------------------------------------------------------------------------- /figures/CENSO/cis4hexen1ol_nmr.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/CENSO/cis4hexen1ol_nmr.png -------------------------------------------------------------------------------- /figures/CENSO/short_censo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/CENSO/short_censo.png -------------------------------------------------------------------------------- /figures/CENSO/solvents.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/CENSO/solvents.png -------------------------------------------------------------------------------- /figures/README: -------------------------------------------------------------------------------- 1 | Put in here all your juicy pictures. 2 | -------------------------------------------------------------------------------- /figures/alagly.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/alagly.png -------------------------------------------------------------------------------- /figures/alaglyconfs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/alaglyconfs.png -------------------------------------------------------------------------------- /figures/alaglydep.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/alaglydep.png -------------------------------------------------------------------------------- /figures/alaglyprot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/alaglyprot.png -------------------------------------------------------------------------------- /figures/benzene_dimer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/benzene_dimer.png -------------------------------------------------------------------------------- /figures/bromochloroethane.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/bromochloroethane.gif -------------------------------------------------------------------------------- /figures/bromochloroethane.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/bromochloroethane.png -------------------------------------------------------------------------------- /figures/claisen.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/claisen.gif -------------------------------------------------------------------------------- /figures/claisen_conv.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/claisen_conv.png -------------------------------------------------------------------------------- /figures/concertedscan.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/concertedscan.gif -------------------------------------------------------------------------------- /figures/confining_anisotropic.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/confining_anisotropic.png -------------------------------------------------------------------------------- /figures/confining_misplaced.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/confining_misplaced.png -------------------------------------------------------------------------------- /figures/confining_shifted.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/confining_shifted.png -------------------------------------------------------------------------------- /figures/constrain.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/constrain.gif -------------------------------------------------------------------------------- /figures/cre-pes.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/cre-pes.png -------------------------------------------------------------------------------- /figures/crest-mf.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/crest-mf.png -------------------------------------------------------------------------------- /figures/crest-v1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/crest-v1.png -------------------------------------------------------------------------------- /figures/crest-v2i.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/crest-v2i.png -------------------------------------------------------------------------------- /figures/crest_cuvaline.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/crest_cuvaline.png -------------------------------------------------------------------------------- /figures/crest_overlay.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/crest_overlay.png -------------------------------------------------------------------------------- /figures/crest_pt.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/crest_pt.png -------------------------------------------------------------------------------- /figures/crest_surface.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/crest_surface.png -------------------------------------------------------------------------------- /figures/crest_ts.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/crest_ts.png -------------------------------------------------------------------------------- /figures/cyclohexane.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/cyclohexane.gif -------------------------------------------------------------------------------- /figures/cyclohexane_conv.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/cyclohexane_conv.png -------------------------------------------------------------------------------- /figures/diphenylacetylene.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/diphenylacetylene.png -------------------------------------------------------------------------------- /figures/dipro.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/dipro.png -------------------------------------------------------------------------------- /figures/directed.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/directed.png -------------------------------------------------------------------------------- /figures/docs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/docs.png -------------------------------------------------------------------------------- /figures/enso/enso-detailed.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/enso/enso-detailed.png -------------------------------------------------------------------------------- /figures/enso/enso-procedure3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/enso/enso-procedure3.png -------------------------------------------------------------------------------- /figures/enso/enso-short.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/enso/enso-short.png -------------------------------------------------------------------------------- /figures/enso/enso_2-methly1pentene.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/enso/enso_2-methly1pentene.png -------------------------------------------------------------------------------- /figures/enso/enso_2methyl-1-pentene.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/enso/enso_2methyl-1-pentene.png -------------------------------------------------------------------------------- /figures/enso/enso_cis4hexen1ol.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/enso/enso_cis4hexen1ol.png -------------------------------------------------------------------------------- /figures/enso/enso_get_spectrum.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/enso/enso_get_spectrum.png -------------------------------------------------------------------------------- /figures/enso/enso_spectrum_2-methyl-1-pentene.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/enso/enso_spectrum_2-methyl-1-pentene.png -------------------------------------------------------------------------------- /figures/enso/structure.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/enso/structure.png -------------------------------------------------------------------------------- /figures/ethane.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/ethane.gif -------------------------------------------------------------------------------- /figures/ethane.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/ethane.png -------------------------------------------------------------------------------- /figures/fix.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/fix.gif -------------------------------------------------------------------------------- /figures/gas.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/gas.gif -------------------------------------------------------------------------------- /figures/gas_slow.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/gas_slow.gif -------------------------------------------------------------------------------- /figures/gbsa-infinity.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/gbsa-infinity.gif -------------------------------------------------------------------------------- /figures/gbsa.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/gbsa.gif -------------------------------------------------------------------------------- /figures/gfnff.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/gfnff.jpg -------------------------------------------------------------------------------- /figures/h0tuning.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/h0tuning.png -------------------------------------------------------------------------------- /figures/imtd-smtd.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/imtd-smtd.png -------------------------------------------------------------------------------- /figures/mit.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/mit.png -------------------------------------------------------------------------------- /figures/notconcertedscan.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/notconcertedscan.gif -------------------------------------------------------------------------------- /figures/ohne.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/ohne.png -------------------------------------------------------------------------------- /figures/oniom_23.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/oniom_23.png -------------------------------------------------------------------------------- /figures/optimize-benzyne-infinity.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/optimize-benzyne-infinity.gif -------------------------------------------------------------------------------- /figures/optimize-benzyne.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/optimize-benzyne.gif -------------------------------------------------------------------------------- /figures/optimize-cp-infinity.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/optimize-cp-infinity.gif -------------------------------------------------------------------------------- /figures/optimize-cp.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/optimize-cp.gif -------------------------------------------------------------------------------- /figures/optimize-ethyne-infinity.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/optimize-ethyne-infinity.gif -------------------------------------------------------------------------------- /figures/optimize-ethyne.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/optimize-ethyne.gif -------------------------------------------------------------------------------- /figures/path-ts.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/path-ts.png -------------------------------------------------------------------------------- /figures/potential_shapes.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/potential_shapes.png -------------------------------------------------------------------------------- /figures/ptb_cover_image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/ptb_cover_image.png -------------------------------------------------------------------------------- /figures/ptb_ir_spectra.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/ptb_ir_spectra.png -------------------------------------------------------------------------------- /figures/ptb_raman_1edn.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/ptb_raman_1edn.png -------------------------------------------------------------------------------- /figures/qcg-micro.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/qcg-micro.png -------------------------------------------------------------------------------- /figures/qcg-supra.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/qcg-supra.png -------------------------------------------------------------------------------- /figures/qcg_Fe.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/qcg_Fe.png -------------------------------------------------------------------------------- /figures/qcg_algo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/qcg_algo.png -------------------------------------------------------------------------------- /figures/qcg_bacillaene.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/qcg_bacillaene.png -------------------------------------------------------------------------------- /figures/qcg_solv_fe.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/qcg_solv_fe.png -------------------------------------------------------------------------------- /figures/qcg_wallpot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/qcg_wallpot.png -------------------------------------------------------------------------------- /figures/qcxms/QCxMS_EI-CID_Flowchart.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/qcxms/QCxMS_EI-CID_Flowchart.png -------------------------------------------------------------------------------- /figures/qcxms2/2pentanone_gfn2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/qcxms2/2pentanone_gfn2.png -------------------------------------------------------------------------------- /figures/spgfn.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/spgfn.png -------------------------------------------------------------------------------- /figures/undirected.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/undirected.png -------------------------------------------------------------------------------- /figures/vimdiffstartend.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/vimdiffstartend.png -------------------------------------------------------------------------------- /figures/wclust1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/wclust1.png -------------------------------------------------------------------------------- /figures/wclustpot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/wclustpot.png -------------------------------------------------------------------------------- /figures/wrongclaisen.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/wrongclaisen.gif -------------------------------------------------------------------------------- /figures/wrongclaisen_conv.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/figures/wrongclaisen_conv.png -------------------------------------------------------------------------------- /logo/akgrimme_logo_final2018_xtbdocs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/logo/akgrimme_logo_final2018_xtbdocs.png -------------------------------------------------------------------------------- /logo/logo_abtgrimme_desktop.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/grimme-lab/xtb_docs/2e3b27f69f1f7c6e7ef1daf2991489c042fb3797/logo/logo_abtgrimme_desktop.png -------------------------------------------------------------------------------- /make.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | 3 | pushd %~dp0 4 | 5 | REM Command file for Sphinx documentation 6 | 7 | if "%SPHINXBUILD%" == "" ( 8 | set SPHINXBUILD=sphinx-build 9 | ) 10 | set SOURCEDIR=source 11 | set BUILDDIR=build 12 | 13 | if "%1" == "" goto help 14 | 15 | %SPHINXBUILD% >NUL 2>NUL 16 | if errorlevel 9009 ( 17 | echo. 18 | echo.The 'sphinx-build' command was not found. Make sure you have Sphinx 19 | echo.installed, then set the SPHINXBUILD environment variable to point 20 | echo.to the full path of the 'sphinx-build' executable. Alternatively you 21 | echo.may add the Sphinx directory to PATH. 22 | echo. 23 | echo.If you don't have Sphinx installed, grab it from 24 | echo.http://sphinx-doc.org/ 25 | exit /b 1 26 | ) 27 | 28 | %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% 29 | goto end 30 | 31 | :help 32 | %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% 33 | 34 | :end 35 | popd 36 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | ablog 2 | sphinx_design 3 | sphinx_copybutton 4 | sphinx_togglebutton 5 | -------------------------------------------------------------------------------- /source/CENSO_docs/abbreviations.rst: -------------------------------------------------------------------------------- 1 | .. _abbreviations: 2 | 3 | Abbreviations 4 | ============= 5 | 6 | .. list-table:: abbreviations 7 | :widths: 30 100 8 | :header-rows: 1 9 | 10 | * - abbreviation 11 | - definition 12 | * - SQM 13 | - semiempirical quantum mechanical (method) 14 | * - ALPB 15 | - analytical linearized Poisson-Boltzmann model 16 | * - GBSA 17 | - generalized born surface approximation 18 | * - DFT 19 | - density functional theory 20 | * - DFA 21 | - density functional approximation 22 | * - FF 23 | - force field 24 | * - CREST 25 | - conformer rotamer ensemble search tool 26 | * - CENSO 27 | - command-line energetic sorting 28 | * - NMR 29 | - nuclear magnetic resonance 30 | * - OR 31 | - optical rotatory dispersion 32 | * - GFN 33 | - Geometry Frequency Noncovalent 34 | * - GCP 35 | - geometric counterpoise correction 36 | 37 | -------------------------------------------------------------------------------- /source/CENSO_docs/censo_extensive_keywords.rst: -------------------------------------------------------------------------------- 1 | .. _censo_extensive_keywords: 2 | 3 | ========================= 4 | Extensive Keyword Options 5 | ========================= 6 | 7 | .. _censo_funcs: 8 | 9 | Functionals 10 | ----------- 11 | 12 | For automated input preparation, CENSO will try to find the functional in an internal lookup dict. 13 | This is due to differences in naming between different QM programs. If the functional string is not 14 | found within this lookup dict, CENSO will not run. 15 | 16 | .. hint:: 17 | 18 | If you want to use a functional unknown to CENSO using ORCA, you might want to set the func to dummy and 19 | use a template file for configuration. 20 | 21 | 22 | .. _censo_bs: 23 | 24 | Basis Sets 25 | ---------- 26 | 27 | The policy for basis sets is to take the provided keyword literally without internal lookup. 28 | This means, you need to provide the basis set keyword already with the correct name 29 | for the QM program you want to utilize. This is not case-sensitive and for TURBOMOLE there is 30 | an internal lookup to check for capitalization. 31 | 32 | .. hint:: 33 | 34 | Please note that, when applying composite methods, the basis keyword will be ignored. 35 | 36 | .. _censo_solv: 37 | 38 | Solvents 39 | -------- 40 | 41 | For each solvation model all available solvents should also be found by CENSO. If there are solvents 42 | missing please file an issue on GitHub or add them to the lookup file yourself (found in ``src/censo/assets```). 43 | -------------------------------------------------------------------------------- /source/CENSO_docs/censo_parallel.rst: -------------------------------------------------------------------------------- 1 | .. _censo_parallel: 2 | 3 | ======================== 4 | Parallelization in CENSO 5 | ======================== 6 | 7 | CENSO parallelizes the local execution of external program calls. For this it uses the built-in 8 | ``multiprocessing`` and ``concurrent`` libraries. At the heart of the parallelization is 9 | the ``execute`` function of the ``censo.parallel`` module. It consists of seven steps: 10 | 11 | 1. Create the joblist from the provided information (conformers, instructions for QM programs, jobtype), 12 | 2. set up the processor for parallel execution, 13 | 3. copying of MO-files (if used), 14 | 4. set the number of OpenMP threads (OMP) per subprocess for each job, 15 | 5. parallel execution, 16 | 6. collection of results and metadata, 17 | 18 | .. hint:: 19 | CENSO cannot be parallelized over multiple nodes. 20 | 21 | If using the ``balance`` option from the general settings section, CENSO will assign the 22 | number of OpenMP threads per job while trying to maximize core utilization at all times, 23 | assuming roughly equal computation times for each job. Since parallelization efficiency 24 | drops off exponentially, this means trying to create as many jobs as possible with as 25 | little number of cores as possible. For the remainder jobs, core utilization is maximized. 26 | 27 | Good results can be expected for small ensembles with expensive computations, although for 28 | large ensembles the new algorithm approaches the efficiency of the basic load balancing strategy 29 | of assigning the same number of OpenMP threads for each job. Generally it is recommended 30 | to enable the ``balance`` option. 31 | 32 | .. warning:: 33 | 34 | In order for CENSO to be able to correctly determine the number of OpenMP threads per job, 35 | the ``maxcores`` option needs to be set appropriately. If you use a workload manager such 36 | as PBS or Slurm, it is probably a good idea to set ``maxcores`` according to the queue 37 | you're submitting to. 38 | -------------------------------------------------------------------------------- /source/CENSO_docs/censo_uvvis.rst: -------------------------------------------------------------------------------- 1 | .. _uvvis: 2 | 3 | ============================= 4 | Calculation of UV/Vis-Spectra 5 | ============================= 6 | 7 | .. contents :: 8 | 9 | 10 | For the calculation of ensemble UV/Vis-Spectra CENSO can use ORCA to compute the excitation wavelengths and 11 | oscillator strengths for each conformer. From the oscillator strengths the maximum extinction coefficients 12 | are calculated based on Boltzmann population. You can find the data for all the excitations 13 | in ``json``-format the file ``excitations.json`` or in tabular format in the output file of the UV/Vis 14 | property calculation. 15 | 16 | Plotting the spectrum 17 | --------------------- 18 | 19 | The calculated extinction coefficients are to be used to calculate a spectrum as a superposition of Gaussians. 20 | The maximum extinction coefficients are calculated for every excitation. Furthermore, the coefficients get weighted 21 | by the population of the originating conformer. For plotting the spectrum, the ``uvvisplot`` script provided in the 22 | ``bin`` directory can be used. 23 | -------------------------------------------------------------------------------- /source/_posts/2021/dftbplus-version-21.2.rst: -------------------------------------------------------------------------------- 1 | :date: 2021-12-13 2 | :author: Sebastian Ehlert 3 | :category: release 4 | :tags: dftbplus xtb 5 | 6 | DFTB+ version 21.2 released 7 | =========================== 8 | 9 | A new version of DFTB+ is now available with support for the xTB methods. 10 | Due to the integration in DFTB+ most of the features available for the DFTB Hamiltonian can be readily used with the xTB Hamiltonians as well, including periodic calculations with k-point sampling, geometry optimizations, molecular dynamics and frequency calculations. 11 | Both GFN1-xTB and GFN2-xTB are available for the DFTB+ version 21.2 at the moment. 12 | 13 | Furthermore, we integrated parts the battle-proven rational function optimizer from ``xtb --opt`` into DFTB+ to allow fast and robust geometry optimizations both for molecular and periodic systems. 14 | Preliminary tests show an order of magnitude improvements in the convergence compared with the previous default (c.f. `dftbplus#862 `_). 15 | 16 | You can find the full changelog for DFTB+ 21.2 `here `_. 17 | 18 | 19 | Installing DFTB+ with xTB support 20 | --------------------------------- 21 | 22 | A complete DFTB+ package is available via `conda-forge`_. 23 | To install the *conda* package manager we recommend the `miniforge `_ installer. 24 | If the *conda-forge* channel is not yet enabled, add it to your channels with 25 | 26 | .. code-block:: bash 27 | 28 | conda config --add channels conda-forge 29 | 30 | Once the *conda-forge* channel has been enabled, DFTB+ can be installed with: 31 | 32 | .. code-block:: bash 33 | 34 | conda install 'dftbplus=*=nompi_*' 35 | 36 | Or to install the MPI enabled version, you can add *mpich* or *openmpi* as MPI provider or just let conda choose: 37 | 38 | .. code-block:: bash 39 | 40 | conda install 'dftbplus=*=mpi_*' 41 | 42 | It is possible to list all of the versions available on your platform with: 43 | 44 | .. code-block:: bash 45 | 46 | conda search dftbplus --channel conda-forge 47 | 48 | Now you are ready to use the ``dftb+`` executable, find the *tblite* library is installed as well as part of the DFTB+ dependencies. 49 | 50 | .. _conda-forge: https://anaconda.org/conda-forge/dftbplus 51 | 52 | 53 | Input structure 54 | --------------- 55 | 56 | Input to DFTB+ is provided by creating a file named ``dftb_in.hsd`` in the custom human-friendly structured data (HSD) format, which is inspired by XML. 57 | The geometry input is provided in the *Geometry* group, either as *xyzFormat* for molecular geometries or as *vaspFormat* for periodic geometries. 58 | To enable the xTB methods the *Hamiltonian* group is set to *xTB*. 59 | In the *xTB* group the *Method* keyword is provided to select between GFN2-xTB, GFN1-xTB and IPEA1-xTB. 60 | 61 | .. code-block:: bash 62 | :caption: Molecular GFN2-xTB calculation 63 | 64 | Geometry = xyzFormat { 65 | <<< "struc.xyz" 66 | } 67 | 68 | Hamiltonian = xTB { 69 | Method = "GFN2-xTB" 70 | } 71 | 72 | To perform periodic calculations with the xTB Hamiltonian only the k-point sampling has to be added to the *xTB* group with *kPointsAndWeights*. 73 | Using the *SuperCellFolding* provides Monkhorst–Pack k-point sampling. 74 | 75 | .. code-block:: bash 76 | :caption: Periodic GFN1-xTB calculation 77 | 78 | Geometry = vaspFormat { 79 | <<< "POSCAR" 80 | } 81 | 82 | Hamiltonian = xTB { 83 | Method = "GFN1-xTB" 84 | kPointsAndWeights = SuperCellFolding { 85 | 2 0 0 86 | 0 2 0 87 | 0 0 2 88 | 0.5 0.5 0.5 89 | } 90 | } 91 | 92 | Instead of providing a *Method* the xTB method can be initialized from a parameter file by providing its path in *ParameterFile*. 93 | 94 | .. code-block:: bash 95 | 96 | # ... 97 | Hamiltonian = xTB { 98 | ParameterFile = "gfn2-xtb.toml" 99 | # ... 100 | } 101 | 102 | Finally, to perform more than just single point calculations, the *Driver* group has to be provided. 103 | Best is to use the new *GeometryOptimization* driver, which defaults to a rational function minimizer as present in the ``xtb`` program package. 104 | For periodic structures the lattice optimization can be enabled by setting *LatticeOpt* to *Yes*. 105 | 106 | .. code-block:: bash 107 | 108 | Driver = GeometryOptimization { 109 | LatticeOpt = Yes 110 | } 111 | 112 | For the full capabilities for DFTB+ check the `reference manual `_. 113 | -------------------------------------------------------------------------------- /source/_posts/2021/dftd4-version-3.2.0.rst: -------------------------------------------------------------------------------- 1 | :date: 2021-05-03 2 | :author: Sebastian Ehlert 3 | :category: release 4 | :tags: dftd4 5 | 6 | DFT-D4 version 3.2.0 released 7 | ============================= 8 | 9 | .. image:: https://github.com/dftd4/dftd4-artwork/raw/main/full-circle/d4-full-circle.svg 10 | :alt: D4 logo 11 | 12 | We released a new version of DFT-D4 further expanding the functionality of the Python API and the integration with QCEngine and ASE. 13 | In this process we simplified the installation of the Python extension module which should now also be possible with pip. 14 | The DFT-D4 program can now also calculate pairwise resolved dispersion energies, both for the pairwise additive and pairwise non-additive contributions to the total dispersion energy. 15 | 16 | Find the complete release notes `here `_. 17 | -------------------------------------------------------------------------------- /source/_posts/2021/qcxms-version-5.0.3.rst: -------------------------------------------------------------------------------- 1 | :date: 2021-06-10 2 | :author: Jeroen Koopman 3 | :category: release 4 | :tags: qcxms 5 | 6 | QCxMS version 5.0.3 released 7 | ============================= 8 | 9 | Recently, we released the `QCxMS program `_ for calculating EI and CID mass spectra using molecular dynamics. 10 | The project moved to GitHub under the `@qcxms `_ namespace and will soon become an open source project, as soon as all major bugs are fixed. 11 | 12 | In this second update, we have started to update the output information provided by the program and especially the cid module and improved the way the automated 13 | *general run-type* of the CID module detemines the number of collisions. This in turn leads to a **greater number** of collisions in the simulation than in the versions before. 14 | 15 | The updated program and detailed release notes can be found `here `_. 16 | -------------------------------------------------------------------------------- /source/_posts/2021/qcxms-version-5.1.0.rst: -------------------------------------------------------------------------------- 1 | :date: 2021-08-06 2 | :author: Jeroen Koopman 3 | :category: release 4 | :tags: qcxms 5 | 6 | QCxMS version 5.1.0 released 7 | ============================= 8 | 9 | .. image:: https://github.com/JayTheDog/QCxMS-Logo/raw/main/qcxms_logo_screen.svg 10 | :alt: QCxMS logo 11 | 12 | This new update of the `QCxMS program `_ changes the way xtb is used inside the code. Instead of a standalone implementation of xtb version 5.8.1 in the source code, 13 | we switched to using the `tblite `_ library, which allows updates to the latest version of xtb. This, in return, leads to a significant **increase in the computational 14 | speed** of calculations done with the *GFNn-xTB* methods, while keeping the code independent from third party software. 15 | 16 | Furthermore, the `PlotMS program `_ has been updated as well. 17 | 18 | For a detailed description of all changes, check out the `GitHub repository `_. 19 | 20 | -------------------------------------------------------------------------------- /source/_posts/2021/qcxms-version-5.1.2.rst: -------------------------------------------------------------------------------- 1 | :date: 2021-08-27 2 | :author: Jeroen Koopman 3 | :category: release 4 | :tags: qcxms 5 | 6 | QCxMS version 5.1.2 released 7 | ============================= 8 | 9 | .. image:: https://github.com/JayTheDog/QCxMS-Logo/raw/main/qcxms_logo_screen.svg 10 | :alt: QCxMS logo 11 | 12 | This new update of the `QCxMS program `_ is linked against the AVX2 processor extension for increased performance. 13 | CID and EI runmode changes and bugfixes are implemented. The local run-script `pqcxms` was re-written and now performs better for parallel calculations. 14 | 15 | For a detailed description of all changes, check out the `GitHub repository `_. 16 | 17 | -------------------------------------------------------------------------------- /source/_posts/2021/xtb-version-6.4.1.rst: -------------------------------------------------------------------------------- 1 | :date: 2021-06-10 2 | :author: Sebastian Ehlert 3 | :category: release 4 | :tags: xtb 5 | 6 | xtb version 6.4.1 released 7 | ========================== 8 | 9 | .. image:: https://github.com/awvwgk/xtb-logo/raw/master/xtb.svg 10 | :alt: xtb logo 11 | 12 | We released a new version of ``xtb`` with a significantly improved memory footprint for large scale calculations and improved parallelisation for frequency calculations. 13 | The parallel evaluation of hessians with GFN-FF is now possible, overall we improved the stablility of the parallelisation which was slightly degraded in version 6.4.0. 14 | For xTB calculations the required ``OMP_STACKSIZE`` has been significantly reduced by restructuring the integral evaluation slightly. 15 | 16 | Also, this version of ``xtb`` now supports the COSMO/CPCM solvation model using the `ddPCM `_ library. 17 | 18 | Note that this version contains an important bugfix in the topology generation for the GFN-FF, which slightly changes the total energies with respect to previous versions. 19 | Old topology files will be invalidated automatically by the new version to avoid running calculations on incorrect topologies. 20 | 21 | Many thanks to Marcel Stahn (`@MtoLStoN `_), Sebastian Spicher (`@sespic `_), Christoph Plett (`@cplett `_), Cyrille Lavigne (`@clavigne `_) and Miguel Steiner (`@steinmig `_) for contributing to this version. 22 | 23 | Find the complete release notes `here `_. 24 | -------------------------------------------------------------------------------- /source/_posts/2022/xtb-version-6.5.0.rst: -------------------------------------------------------------------------------- 1 | :date: 2022-05-15 2 | :author: Sebastian Ehlert 3 | :category: release 4 | :tags: xtb 5 | 6 | xtb version 6.5.0 released 7 | ========================== 8 | 9 | .. image:: https://github.com/awvwgk/xtb-logo/raw/master/xtb.svg 10 | :alt: xtb logo 11 | 12 | We are happy to release a new version of ``xtb`` with exciting new features. 13 | First of all, we improved the user-friendliness of the error messages in the geometry reader by adopting our `IO-library `__, which is already in wide use in `dftd4 `__, `gcp `__ and other projects. 14 | No more *invalid input provided* obscure error messages, but actual pointers on what went wrong with the input. 15 | 16 | .. code:: text 17 | 18 | Error: Conflicting lattice and cell groups 19 | --> struc.coord:37:1-5 20 | | 21 | 35 | $lattice angs 22 | | -------- lattice first defined here 23 | : 24 | 37 | $cell angs 25 | | ^^^^^ conflicting cell group 26 | | 27 | 28 | We also improved the capability of existing geometry readers to keep up to date with the parent programs, for example we now support the ``$eht charge=0 unpaired=0`` line to set the system charge and number of unpaired electrons, which was added in a Turbomole 7.5. 29 | Furthermore, we are happy to have now support for QChem molecule files (``.qchem``), FHI-aims geometry inputs (``geometry.in``) and QCSchema formatted JSON (``.json``). 30 | 31 | Other new features in this release are the preliminary ONIOM calculator to combine GFNn-xTB and GFN-FF with DFT or the new inspection feature for the GFN-FF topology via the ``wrtopo`` option. 32 | This release also includes several important bugfixes for the GFN-FF, the numerical hessian evaluation, overflow fixes and many others. 33 | 34 | Many thanks to Christian Hölzer (`@hoelzerC `__), Albert Katbashev (`@Albkat `__), Jeroen Koopman (`@JayTheDog `__), Hagen Neugebauer (`@haneug `__), Felix Pultar (`@pultar `__), Thomas Rose (`@Thomas3R `__), Jordy Schifferstein (`@Jordy-prog `_), Marcel Stahn (`@MtoLStoN `__) for contributing to this version of ``xtb``. 35 | 36 | Find the complete release notes `here `__. 37 | -------------------------------------------------------------------------------- /source/_static/custom.css: -------------------------------------------------------------------------------- 1 | .wy-table-responsive table td, .wy-table-responsive table th { 2 | /* !important prevents the common CSS stylesheets from 3 | overriding this as on RTD they are loaded after this stylesheet */ 4 | white-space: normal !important; 5 | } 6 | 7 | .wy-table-responsive { 8 | overflow: visible !important; 9 | } -------------------------------------------------------------------------------- /source/basics.rst: -------------------------------------------------------------------------------- 1 | .. _quickstart: 2 | 3 | ---------------------------- 4 | Quickstart into Production 5 | ---------------------------- 6 | 7 | This chapter should serve as a quickstart tutorial guiding you through your first 8 | calculation employing the xTB methods. 9 | As an example, the equilibrium geometry of a water molecule is calculated. 10 | The description here is based on ``xtb`` version 6.2.2. 11 | 12 | .. contents:: 13 | 14 | 15 | .. note:: The program can almost entirely controlled by the command-line, if you 16 | need more control you should resort to the :ref:`detailed-input` file. 17 | 18 | There are four main run types in ``xtb``, most other run types are 19 | composite types that try to provide convenient combinations from 20 | those main run types. 21 | 22 | Singlepoint Calculations 23 | ======================== 24 | 25 | Independent of all other commands, there will always be a singlepoint 26 | calculation carried out at the very beginning. To calculate something 27 | ``xtb`` needs information about the molecular geometry and the kind 28 | of atoms present. 29 | 30 | The default input format is either the Turbomole coordinate file 31 | as a ``$coord`` data group. 32 | 33 | .. code:: bash 34 | 35 | > cat coord 36 | $coord 37 | 0.00000000000000 0.00000000000000 -0.73578586109551 o 38 | 1.44183152868459 0.00000000000000 0.36789293054775 h 39 | -1.44183152868459 0.00000000000000 0.36789293054775 h 40 | $end 41 | 42 | > xtb coord 43 | 44 | Like in Turbomole the coordinates can be given in Bohr (default) 45 | or Ångström (``$coord angs``) or fractional coordinates (``$coord frac``). 46 | Optional data groups like the systems periodicity (``$periodic``), 47 | lattice parameters (``$lattice [bohr|angs]``) and cell parameters 48 | (``$cell [bohr|angs]``) can be provided as well. 49 | 50 | The following input for a MgO crystal utilize this data groups: 51 | 52 | .. code:: text 53 | 54 | $coord frac 55 | 0.00 0.00 0.00 mg 56 | 0.50 0.50 0.50 o 57 | $periodic 3 58 | $cell 59 | 5.798338236 5.798338236 5.798338236 60. 60. 60. 60 | $end 61 | 62 | .. note:: In previous version the coord data group had to start in the 63 | first line, this constraint has been relaxed by now. 64 | 65 | Any valid xyz file can be used to provide coordinates and requires the 66 | file extension ``.xyz``. This format does not support periodic boundary conditions. 67 | 68 | ``xtb`` also supports DFTB+ genFormat files (``.gen``), protein database files (``.pdb``) 69 | mol-files (``.mol``) and structure-data files (``.sdf``), if the corresponding suffix 70 | is encountered. Note that you cannot provide a mol file with the extension sdf. 71 | Vasp's POSCAR or CONTCAR files are read if the file is named as such. 72 | 73 | By default ``xtb`` will search for ``.CHRG`` and ``.UHF`` files and obtain 74 | from these the molecular charge and the number of unpaired electrons, 75 | respectively. The molecular charge can also be specified by 76 | 77 | .. code:: sh 78 | 79 | > xtb molecule.xyz --chrg +1 80 | 81 | which is equivalent to 82 | 83 | .. code:: sh 84 | 85 | > echo +1 > .CHRG && xtb molecule.xyz 86 | 87 | 88 | This also works for the unpaired electrons as in 89 | 90 | .. code:: sh 91 | 92 | > xtb --uhf 2 input.sdf 93 | 94 | Note that the position of the input coordinates is totally unaffected 95 | by any command-line arguments, if you are not sure, whether ``xtb`` tries 96 | to interpret your filename as flag use ``--`` to stop the parsing 97 | as command-line options for all following arguments. 98 | 99 | .. code:: sh 100 | 101 | > xtb -- -oh.xyz 102 | 103 | To select the parametrization of the xTB method you can currently choose 104 | from three different geometry, frequency and non-covalent interactions (GFN) 105 | parametrization, which differ mostly in the cost--accuracy ratio, 106 | 107 | .. code:: sh 108 | 109 | > xtb --gfn 2 coord 110 | 111 | to choose GFN2-xTB, which is also the default parametrization. Also 112 | available are GFN1-xTB, and GFN0-xTB. 113 | 114 | Sometimes you might face difficulties converging the self consistent 115 | charge iterations, in this case it is usually a good idea to increase 116 | the electronic temperature and to restart at normal temperature 117 | 118 | .. code:: sh 119 | 120 | > xtb --etemp 1000.0 coord && xtb --restart coord 121 | 122 | Geometry Optimizations 123 | ====================== 124 | 125 | The main purpose of the xTB methods is to provide good geometries, 126 | so the ``xtb`` comes with a build-in geometry optimizer, which usually 127 | does a decent job. It is invoked by 128 | 129 | .. code:: bash 130 | 131 | > xtb coord --opt 132 | > ls 133 | coord xtbopt.coord xtbopt.log ... 134 | 135 | The optimized coordinates is written to a new file (``xtbopt.coord``), which is 136 | in the same format as the input geometry. You can view the geometry optimization 137 | by opening the ``xtbopt.log`` with your favorite molecule viewer. 138 | The log-file is in Xmol format and contains the current total energy 139 | and the gradient norm in the comment line, ``gmolden`` usually works fine 140 | for this. 141 | 142 | A successful geometry optimization will print somewhere along the lines 143 | 144 | .. code:: 145 | 146 | *** GEOMETRY OPTIMIZATION CONVERGED AFTER 43 ITERATIONS *** 147 | 148 | ------------------------------------------------------------------------ 149 | total energy gain : -0.0094907 Eh -5.9555 kcal/mol 150 | total RMSD : 0.7677834 a0 0.4063 Å 151 | ------------------------------------------------------------------------ 152 | 153 | after finishing the optimization procedures, while in all other cases 154 | that not exit in error 155 | 156 | .. code:: 157 | 158 | *** FAILED TO CONVERGE GEOMETRY OPTIMIZATION IN 500 ITERATIONS *** 159 | 160 | will be printed, additionally a ``NOT_CONVERGED`` file is created in the 161 | working directory, which might become handy for bulk jobs. 162 | 163 | To get a geometry optimization to converge can be a hard job, usually 164 | the xTB methods can repair a lot, you might want to start from GFN0-xTB 165 | which does not have convergence issues and than improve with GFN2-xTB. 166 | Maybe you have to adjust the geometry by hand again, if even this fails. 167 | 168 | ``xtb`` offers eight predefined levels for the geometry optimization, 169 | which can be chosen by appending the level to the optimization flag as in 170 | 171 | .. code:: bash 172 | 173 | > xtb coord --opt tight 174 | 175 | The thresholds defined by simple keywords are given here 176 | 177 | +---------+----------+--------------+----------+ 178 | | level | Econv/Eh | Gconv/Eh·α⁻¹ | Accuracy | 179 | +---------+----------+--------------+----------+ 180 | | crude | 5 × 10⁻⁴ | 1 × 10⁻² | 3.00 | 181 | +---------+----------+--------------+----------+ 182 | | sloppy | 1 × 10⁻⁴ | 6 × 10⁻³ | 3.00 | 183 | +---------+----------+--------------+----------+ 184 | | loose | 5 × 10⁻⁵ | 4 × 10⁻³ | 2.00 | 185 | +---------+----------+--------------+----------+ 186 | | lax | 2 × 10⁻⁵ | 2 × 10⁻³ | 2.00 | 187 | +---------+----------+--------------+----------+ 188 | | normal | 5 × 10⁻⁶ | 1 × 10⁻³ | 1.00 | 189 | +---------+----------+--------------+----------+ 190 | | tight | 1 × 10⁻⁶ | 8 × 10⁻⁴ | 0.20 | 191 | +---------+----------+--------------+----------+ 192 | | vtight | 1 × 10⁻⁷ | 2 × 10⁻⁴ | 0.05 | 193 | +---------+----------+--------------+----------+ 194 | | extreme | 5 × 10⁻⁸ | 5 × 10⁻⁵ | 0.01 | 195 | +---------+----------+--------------+----------+ 196 | 197 | 198 | The energy convergence (Econv) is the allowed change in the total energy 199 | at convergence, while the gradient convergence (Gconv) is the 200 | allowed change in the gradient norm at convergence. The accuracy 201 | is handed to the singlepoint calculations for integral cutoffs and 202 | self consistent field convergence criteria and is adjusted to fit 203 | the geometry convergence thresholds automatically. 204 | 205 | The xTB methods are completely analytical, so you can in principle 206 | converge your results down to machine precision. Converging it 207 | down to the lower limit is more a development feature than a 208 | real life application but always possible. 209 | 210 | Characterisation of Stationary Points 211 | ===================================== 212 | 213 | In ``xtb`` second derivatives are implemented by finite differences methods 214 | (numerical second derivatives). Normally you want to calculate the Hessian 215 | directly after a successful geometry optimization, this is done by using 216 | 217 | .. code:: bash 218 | 219 | > xtb coord --ohess 220 | 221 | For the calculation on the input geometry use ``--hess`` instead. 222 | 223 | Dealing with Small Imaginary Frequencies 224 | ---------------------------------------- 225 | 226 | For small imaginary modes ``xtb`` offers an automatic distortion feature 227 | of these modes, say you have optimized a geometry and performed 228 | a frequency calculation which leads to an imaginary frequency of 229 | 14 wavenumbers: 230 | 231 | .. code:: 232 | 233 | > xtb coord --ohess 234 | ... 235 | ------------------------------------------------- 236 | | Frequency Printout | 237 | ------------------------------------------------- 238 | projected vibrational frequencies (cm-1) 239 | eigval : -0.00 -0.00 0.00 0.00 0.00 0.00 240 | eigval : -14.26 8.12 9.26 12.09 15.85 17.73 241 | eigval : 19.45 28.85 39.18 41.30 64.61 71.84 242 | ... 243 | imag cut-off (cm-1) : 5.00 244 | found 1 significant imaginary frequency 245 | writing imag mode distorted coords to 246 | for further optimization. 247 | ... 248 | 249 | In this case ``xtb`` will generate a distorted structure, you can continue to 250 | optimize with 251 | 252 | .. code:: 253 | 254 | > xtb xtbhess.coord --ohess 255 | ... 256 | ------------------------------------------------- 257 | | Frequency Printout | 258 | ------------------------------------------------- 259 | projected vibrational frequencies (cm-1) 260 | eigval : -0.00 -0.00 -0.00 -0.00 0.00 0.00 261 | eigval : 2.02 7.99 10.10 12.08 16.16 18.57 262 | eigval : 23.88 28.93 38.35 42.18 64.86 73.76 263 | ... 264 | 265 | The optimization will only take a few steps and the artifical imaginary 266 | frequency is gone after checking the frequency calculation. 267 | -------------------------------------------------------------------------------- /source/capi.rst: -------------------------------------------------------------------------------- 1 | .. _api: 2 | 3 | --------------------------------------------- 4 | C API to the extended tight binding program 5 | --------------------------------------------- 6 | 7 | The ``xtb`` program can included in other application by its 8 | C application programmable interface (API) for all languages that 9 | cannot access the Fortran modules directly. 10 | The API declarations are given in ``xtb.h`` 11 | 12 | .. important:: 13 | 14 | The C API is considered stable with version 6.3.0 and will 15 | be kept compatible to following versions. 16 | 17 | Previous experimental API versions from the 6.2 series are 18 | deprecated. 19 | 20 | The C side has to work with four different Fortran objects which are 21 | allocated and deallocated on the Fortran side and only provided as 22 | opaque data pointer. 23 | 24 | Generally the first set for every API call is to construct a 25 | calculation environment ``xtb_TEnvironment``, which handles the input 26 | and output streams and the error log. 27 | The API will not perform any calculation if a null pointer is passed 28 | instead of the environment and fail silently. 29 | Note that once the environment has caught on an error all further 30 | API calls will fail unless the environment is freed again and the 31 | error has been handled. 32 | 33 | ``xtb`` provides a persistent environment as well which is handled 34 | entirely by the API. Producing an error for this environment is 35 | consider fatal and will halt the program (usually via drastic means, 36 | *i.e.*, without giving the caller a way to react). 37 | This case is always considered a bug in the API and should be reported. 38 | 39 | The input data for the calculation is generated as molecular 40 | structure data ``xtb_TMolecule``. Note that the number of atoms, 41 | the atomic number, the boundary conditions, total charge and 42 | multiplicity are immutable and require to reconstruct the object. 43 | Cartesian coordinates and lattice parameters are provided in Bohr 44 | and can be updated after the object has been constructed. 45 | Both the update and the constructor will fail on invalid input, 46 | which are to close interatomic distances or atomic number outside of 47 | the range 1 to 118 (while individual methods might impose additional 48 | constraints). 49 | 50 | The actual calculation can be performed with a single point 51 | calculator ``xtb_TCalculator`` which must be loaded with a particular 52 | parametrisation before it can be used for a calculation. 53 | GFN2-xTB and GFN1-xTB can safely load their parametrisation without 54 | a parameter file. For the experimental GFN0-xTB a parameter file 55 | is required in the ``XTBPATH`` or must be provided by the API. 56 | The GFN-FF can also provide its own parameters internally but 57 | API support is still experimental. 58 | 59 | Finally, the calculation results are stored in the ``xtb_TResults`` 60 | object which can also be used to restart calculations from previous 61 | runs (*e.g.* after updating coordinates). 62 | The calculation results can be queried for properties they will 63 | return in error in case the property is not available. 64 | Passing calculation results from one calculator to another will 65 | usually result in dimension missmatches, it is recommended to 66 | reconstruct the results object for this purpose. 67 | Generally, the API tries to be particular flexible in this case 68 | and will try to reallocate the individual components as necessary. 69 | Note that this can fail in particular if the total charge or 70 | multiplicity of the molecular structure has changed. 71 | 72 | A simple example program to obtain the total energy from a 73 | GFN2-xTB calculation is given here. 74 | 75 | .. code-block:: c 76 | 77 | #include 78 | 79 | #include "xtb.h" 80 | 81 | int main (int argc, char** argv) 82 | { 83 | double energy = 0.0; 84 | int const natoms = 7; 85 | int const attyp[7] = {6,6,6,1,1,1,1}; 86 | double const charge = 0.0; 87 | int const uhf = 0; 88 | double const coord[3*7] = 89 | {0.00000000000000, 0.00000000000000,-1.79755622305860, 90 | 0.00000000000000, 0.00000000000000, 0.95338756106749, 91 | 0.00000000000000, 0.00000000000000, 3.22281255790261, 92 | -0.96412815539807,-1.66991895015711,-2.53624948351102, 93 | -0.96412815539807, 1.66991895015711,-2.53624948351102, 94 | 1.92825631079613, 0.00000000000000,-2.53624948351102, 95 | 0.00000000000000, 0.00000000000000, 5.23010455462158}; 96 | 97 | /* 98 | * All objects except for the molecular structure can be 99 | * constructued without other objects present. 100 | * 101 | * The construction of the molecular structure locks the 102 | * number of atoms, atomic number, total charge, multiplicity 103 | * and boundary conditions. 104 | **/ 105 | xtb_TEnvironment env = xtb_newEnvironment(); 106 | xtb_TCalculator calc = xtb_newCalculator(); 107 | xtb_TResults res = xtb_newResults(); 108 | xtb_TMolecule mol = xtb_newMolecule( 109 | env, &natoms, attyp, coord, &charge, &uhf, NULL, NULL); 110 | if (xtb_checkEnvironment(env)) { 111 | xtb_showEnvironment(env, NULL); 112 | return 1; 113 | } 114 | 115 | /* 116 | * Apply changes to the environment which will be respected 117 | * in all further API calls. 118 | **/ 119 | xtb_setVerbosity(env, XTB_VERBOSITY_FULL); 120 | if (xtb_checkEnvironment(env)) { 121 | xtb_showEnvironment(env, NULL); 122 | return 1; 123 | } 124 | 125 | /* 126 | * Load a parametrisation, the last entry is a char* which can 127 | * be used to provide a particular parameter file. 128 | * 129 | * Otherwise the XTBPATH environment variable is used to find 130 | * parameter files. 131 | * 132 | * The calculator has to be reconstructed if the molecular 133 | * structure is reconstructed. 134 | **/ 135 | xtb_loadGFN2xTB(env, mol, calc, NULL); 136 | if (xtb_checkEnvironment(env)) { 137 | xtb_showEnvironment(env, NULL); 138 | return 1; 139 | } 140 | 141 | /* 142 | * Actual calculation, will populate the results object, 143 | * the API can raise errors on failed SCF convergence or other 144 | * numerical problems. 145 | * 146 | * Not supported boundary conditions are usually raised here. 147 | **/ 148 | xtb_singlepoint(env, mol, calc, res); 149 | if (xtb_checkEnvironment(env)) { 150 | xtb_showEnvironment(env, NULL); 151 | return 1; 152 | } 153 | 154 | /* 155 | * Query the environment for properties, an error in the environment 156 | * is not considered blocking for this calls and allows to query 157 | * for multiple entries before handling possible errors 158 | **/ 159 | xtb_getEnergy(env, res, &energy); 160 | if (xtb_checkEnvironment(env)) { 161 | xtb_showEnvironment(env, NULL); 162 | return 1; 163 | } 164 | 165 | /* 166 | * deconstructor will deallocate the objects and overwrite the 167 | * pointer with NULL 168 | **/ 169 | xtb_delResults(&res); 170 | xtb_delCalculator(&calc); 171 | xtb_delMolecule(&mol); 172 | xtb_delEnvironment(&env); 173 | 174 | return 0; 175 | } 176 | 177 | The header additionally defines macros for the version of the ``xtb`` API 178 | to guard usage of API functionalities introduced in particular versions. 179 | -------------------------------------------------------------------------------- /source/commandline.rst: -------------------------------------------------------------------------------- 1 | .. _commandline: 2 | 3 | ------------------- 4 | Commandline Usage 5 | ------------------- 6 | 7 | For ``xtb`` we usually enjoy to build our workflows via commandline, 8 | so most tasks can be performed without ever writing any kind of input file 9 | (except for the geometry input, of course). 10 | The man page can be found `here `_. 11 | 12 | .. note:: If you need more control you should resort to the :ref:`detailed-input` 13 | file. 14 | 15 | .. contents:: 16 | 17 | Runtypes 18 | ======== 19 | 20 | The most basic flags used in ``xtb`` are the runtypes. We have a bunch of 21 | them, but many of the elaborate composite runtypes are constructed from 22 | four basic runtypes: singlepoint (SP), geometry optimization (ANCopt), 23 | frequency calculation (Hessian) and molecular dynamics (MD). 24 | Every calculation performs the basic setup and at some (resonable) point 25 | a property calculation. 26 | 27 | Singlepoint 28 | :flag: ``--scc`` 29 | :description: 30 | just self-consistent charge (SCC) calculation. 31 | See :ref:`sp` for details. 32 | :queue: 33 | setup, SP, properties 34 | 35 | Gradient 36 | :flag: ``--grad`` 37 | :description: 38 | self-consistent charge (SCC) calculation, afterwards energy and gradient 39 | will be printed in a Turbomole readable format 40 | :queue: 41 | setup, SP, properties 42 | 43 | Vertical IP 44 | :flag: ``--vip`` 45 | :description: 46 | vertical ionisation potential (IP), calculates SCC on input structure and 47 | than removes an electron to perform another SCC calculation. 48 | :queue: 49 | setup, SP, SP, properties 50 | 51 | Vertical EA 52 | :flag: ``--vea`` 53 | :description: 54 | vertical electron affinity (EA), calculates SCC on input structure and 55 | than adds an electron to perform another SCC calculation. 56 | :queue: 57 | setup, SP, SP, properties 58 | 59 | Vertical IP and EA 60 | :flag: ``--vipea`` 61 | :description: 62 | both IP and EA are calculate by removing and adding an electron, 63 | respectively. 64 | :queue: 65 | setup, SP, SP, SP, properties 66 | 67 | Global Electrophilicity Index 68 | :flag: ``--vomega`` 69 | :description: 70 | global electrophilicity index from vertical IP and EA. 71 | :queue: 72 | setup, SP, SP, SP, properties 73 | 74 | Fukui Indices 75 | :flag: ``--vfukui`` 76 | :description: 77 | calculates Mulliken partial charges from the neutral, positive and 78 | negatively charged structure and calculates Fukui indices. 79 | :queue: 80 | setup, SP, SP, SP, properties 81 | 82 | Dimer Projection Method DIPRO 83 | :flag: ``--dipro`` 84 | :description: 85 | calculates the electronic coupling integrals J_ab and J_ab,eff between 86 | two fragments 87 | :queue: 88 | setup, SP, SP, SP, properties 89 | 90 | Electrostatic Potential 91 | :flag: ``--esp`` 92 | :description: 93 | calculate electrostatic potential on VdW-grid 94 | :queue: 95 | setup, SP, properties (with ESP calculation) 96 | 97 | STM picture 98 | :flag: ``--stm`` 99 | :description: 100 | simulate a STM measurement (molecule should be aligned to xy-plane) 101 | :queue: 102 | setup, SP, properties (with STM calculation) 103 | 104 | Geometry optimization 105 | :flag: ``--opt`` 106 | :description: 107 | approximate normal coordinate optimization, performs an initial singlepoint 108 | calculation and a final singlepoint calculation on the optimized structure. 109 | See :ref:`geometry optimization` for details. 110 | :queue: 111 | setup, SP, ANCopt, SP, properties 112 | 113 | Minimum Hopping 114 | :flag: ``--metaopt`` 115 | :description: 116 | try to find conformers by geometry optimization, for each minimum located 117 | a bias potential is generated to push the optimizer to another local minimum. 118 | :queue: 119 | setup, SP, ANCopt, SP, properties, ANCopt, ... 120 | 121 | Guided Path Finder 122 | :flag: ``--path [file]`` 123 | :description: 124 | apply a bias potential between the input and final geometry (from `file`) 125 | and force the geometry optimizer to generate a path between the two structures. 126 | :queue: 127 | setup, SP, properties, ANCopt, ... 128 | 129 | Modefollowing 130 | :flag: ``--modef mode`` 131 | :description: 132 | follow ``mode`` which specifies the nth eigenmode from a previously done 133 | frequency calculation. 134 | :queue: 135 | setup, SP, properties, ANCopt, ... 136 | 137 | Frequency calculation 138 | :flag: ``--[o]hess`` 139 | :description: 140 | second derivative calculation, see :ref:`frequencies` 141 | :queue: 142 | setup, SP, [ANCopt, SP,] SP, Hessian, properties 143 | 144 | Molecular dynamics 145 | :flag: ``--[o]md`` 146 | :description: 147 | molecular dynamics simulation, see :ref:`md` for details 148 | :queue: 149 | setup, SP, [ANCopt, SP,] properties, MD 150 | 151 | Metadynamics 152 | :flag: ``--metadyn [snapshots]`` 153 | :description: 154 | activates metadynamics simulation on start geometry, where 155 | ``snapshots`` is the number of structures from the trajectory 156 | should be used in the biasing potential. 157 | See :ref:`mtd` for details. 158 | :queue: 159 | setup, SP, properties, MD 160 | 161 | Simulated annealing 162 | :flag: ``--siman`` 163 | :description: 164 | performs a number of simulated annealing steps on the input 165 | coordinates and tries to find a conformer ensemble. 166 | We recommend the CREST workflow (see :ref:`crest`) instead of this runtyp 167 | since it is faster and more reliable in finding the lowest conformer. 168 | **This runtyp has been deprecated and removed in version 6.2!** 169 | :queue: 170 | setup, SP, properties, MD, ANCopt, ... 171 | 172 | Options 173 | ======= 174 | 175 | -c, --chrg INT 176 | specify molecular charge as *INT*, overrides ``.CHRG`` file and ``xcontrol`` option 177 | 178 | -u, --uhf INT 179 | specify Nalpha-Nbeta as *INT*, overrides ``.UHF`` file and ``xcontrol`` option 180 | 181 | --gfn INT 182 | specify parametrisation of GFN-xTB (default = 2) 183 | 184 | --etemp REAL 185 | electronic temperature (default = 300K) 186 | 187 | -a, --acc REAL 188 | accuracy for SCC calculation, lower is better (default = 1.0) 189 | 190 | --vparam FILE 191 | Parameter file for vTB calculation 192 | 193 | --alpb SOLVENT [reference] 194 | analytical linearized Poisson-Boltzmann (ALPB) model, 195 | available solvents are *acetone*, *acetonitrile*, *aniline*, *benzaldehyde*, 196 | *benzene*, *ch2cl2*, *chcl3*, *cs2*, *dioxane*, *dmf*, *dmso*, *ether*, 197 | *ethylacetate*, *furane*, *hexadecane*, *hexane*, *methanol*, *nitromethane*, 198 | *octanol*, *woctanol*, *phenol*, *toluene*, *thf*, *water*. 199 | The solvent input is not case-sensitive. 200 | The Gsolv reference state can be chosen as *reference* or *bar1M* (default). 201 | 202 | -g, --gbsa SOLVENT [reference] 203 | generalized born (GB) model with solvent accessible surface (SASA) model, 204 | available solvents are *acetone*, *acetonitrile*, *benzene* (only GFN1-xTB), 205 | *CH2Cl2*, *CHCl3*, *CS2*, *DMF* (only GFN2-xTB), *DMSO*, *ether*, *H2O*, 206 | *methanol*, *n-hexane* (only GFN2-xTB), *THF* and *toluene*. 207 | The solvent input is not case-sensitive. 208 | The Gsolv reference state can be chosen as *reference* or *bar1M* (default). 209 | 210 | --cma 211 | shifts molecule to center of mass and transforms cartesian coordinates 212 | into the coordinate system of the principle axis (not affected by 213 | ``isotopes``-file). 214 | 215 | --pop 216 | requests printout of Mulliken population analysis (done by default) 217 | 218 | --molden 219 | requests printout of molden file 220 | 221 | --dipole 222 | requests dipole printout (done by default) 223 | 224 | --wbo 225 | requests Wiberg bond order printout (done by default) 226 | 227 | --lmo 228 | requests localization of orbitals 229 | 230 | --fod 231 | requests FOD calculation 232 | 233 | -I, --input FILE 234 | use *FILE* as input source for ``xcontrol(7)`` instructions 235 | 236 | --namespace STRING 237 | give this ``xtb(1)`` run a namespace. All files, even temporary 238 | ones, will be named according to *STRING*. 239 | 240 | --copy, --nocopy 241 | copies the ``xcontrol`` file at startup (default = false) 242 | 243 | --restart, --norestart 244 | restarts calculation from ``xtbrestart`` (default = true) 245 | 246 | -P, --parallel INT 247 | number of parallel processes 248 | 249 | --define 250 | performs automatic check of input and terminate 251 | 252 | --citation 253 | print citation and terminate 254 | 255 | --license 256 | print license and terminate 257 | 258 | -v, --verbose 259 | be more verbose (not supported in every unit) 260 | 261 | -s, --silent 262 | clutter the screen less (not supported in every unit) 263 | 264 | --strict 265 | turns all warnings into hard errors 266 | 267 | -h, --help 268 | show help page 269 | -------------------------------------------------------------------------------- /source/community/gaussian.rst: -------------------------------------------------------------------------------- 1 | Gaussian interface 2 | ================== 3 | 4 | Projects to interface *xtb* with with `Gaussian `_. 5 | 6 | xtb-gaussian 7 | ------------ 8 | 9 | A perl wrapper script to make the *xtb* binary usable with the ``external`` command. 10 | The source code is hosted on GitHub: `aspuru-guzik-group/xtb-gaussian `_. 11 | 12 | Requires an existing *xtb* installation, the *xtb* binary has to be available in the *PATH*. 13 | The script *xtb-gaussian* has to be available in the *PATH* as well and is used to invoke *xtb* from Gaussian using the ``external`` command: 14 | 15 | .. code-block:: text 16 | 17 | %chk=ts 18 | # external="xtb-gaussian -P 12 --etemp 300.0" 19 | opt=(calcfc,ts,noeigentest,nodownhill,nomicro) 20 | 21 | Command line arguments provided to the *xtb-gaussian* wrapper will be passed through to the *xtb* program. 22 | 23 | 24 | gau_xtb 25 | ------- 26 | 27 | A shell script wrapper for *xtb* with additional tools written in Fortran. 28 | The project homepage can be `here `_. 29 | -------------------------------------------------------------------------------- /source/community/index.rst: -------------------------------------------------------------------------------- 1 | Community resources 2 | =================== 3 | 4 | This space is reserved for community developed tooling around *xtb*, *crest* and others. 5 | Here we want to highlight frameworks and programs that depend or build on the methods implemented in *xtb*, interfaces which connect *xtb* with other quantum chemistry programs, or tools that make *xtb* available for special applications. 6 | 7 | 8 | .. note:: 9 | 10 | This section is currently under construction. 11 | Many great projects building on *xtb* are still missing. 12 | We appreciate any help with filling in the gaps. 13 | 14 | 15 | .. toctree:: 16 | 17 | gaussian 18 | pysisyphus 19 | pyvibms 20 | scine 21 | 22 | -------------------------------------------------------------------------------- /source/community/pysisyphus.rst: -------------------------------------------------------------------------------- 1 | Pysisyphus 2 | ========== 3 | 4 | .. image:: https://img.shields.io/github/v/release/eljost/pysisyphus?label=pysisyphus 5 | :target: https://github.com/eljost/pysisyphus/releases/latest 6 | :alt: GitHub release 7 | 8 | Python suite for optimization of stationary points on ground- and excited states PES and determination of reaction paths. 9 | The source code is hosted on GitHub: `eljost/pysisyphus `_. 10 | The projects features an `extensive documentation `_ and example usage together with *xtb*. 11 | -------------------------------------------------------------------------------- /source/community/pyvibms.rst: -------------------------------------------------------------------------------- 1 | PyVibMS 2 | ======= 3 | 4 | To visualize the vibrational modes calculated by xtb (via ``--hess`` or ``--ohess``), find the ``g98.out`` file which collects the vibrational modes and frequencies. 5 | 6 | Lauch PyVibMS in a new PyMOL window, load the ``g98.out`` file by changing the file type into **Output File (*.out)**. Change the program type from **XYZ** to **xtb (g98.out file)**, check the **Has. Vib. Info.** box, click **Load** button. 7 | 8 | Then vibrational modes can be visualized as following 9 | 10 | .. image:: https://raw.githubusercontent.com/smutao/PyVibMS/83e503c0abf3f5f93cc667d28f67a433073c6757/examples/xtb-640/xtb-pyvibms-shot.png 11 | :width: 650 12 | :target: https://github.com/smutao/PyVibMS 13 | 14 | The project homepage can is https://github.com/smutao/PyVibMS. It requires PyMOL 2.5+ to be installed. 15 | 16 | -------------------------------------------------------------------------------- /source/community/scine.rst: -------------------------------------------------------------------------------- 1 | SCINE - XTB Wrapper -- A Wrapper for Tight Binding 2 | ================================================== 3 | 4 | Introduction 5 | ------------ 6 | 7 | SCINE XTB Wrapper is a wrapper around `xtb `_, it 8 | exports: 9 | 10 | - GFN0-xTB 11 | - GFN1-xTB 12 | - GFN2-xTB 13 | - GFN-FF 14 | 15 | into the SCINE tool chain. 16 | Each method is represented by its own ``Calculator`` and the entire wrapper 17 | constitutes a SCINE module that can be loaded dynamically at runtime. 18 | For more information on these concepts see the ``Scine::Core`` 19 | `SCINE Core repository `_. 20 | 21 | License and Copyright Information 22 | --------------------------------- 23 | 24 | The SCINE XTB wrapper is distributed under the BSD 3-clause "New" or "Revised" 25 | License. For more license and copyright information, see the file ``LICENSE.txt`` 26 | in the `XTB Wrapper repository `_. 27 | 28 | Note: this license does not cover the original `xtb` source code. 29 | 30 | Installation and Usage 31 | ---------------------- 32 | 33 | The wrapper can be built and installed using the following commands:: 34 | 35 | mkdir build 36 | cd build 37 | cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX= .. 38 | make -j 39 | make install 40 | 41 | This will generate and install both the main `xtb` code and the wrapper in the 42 | form of the file ``xtb.module.so`` that can be used in SCINE. 43 | 44 | In order to make XTB available to SCINE the following two environment variables 45 | need to be set:: 46 | 47 | export XTBPATH=/share/xtb 48 | export SCINE_MODULE_PATH=$SCINE_MODULE_PATH:/lib 49 | 50 | Afterwards, SCINE programs such as `ReaDuct `_ 51 | will pick up XTB's existence and it will be possible to request the implemented 52 | methods. 53 | 54 | Python 55 | ...... 56 | 57 | The SCINE XTB wrapper is also available via Python. 58 | The underlying SCINE module can be loaded and its implemented calculators 59 | accessed using the standard ``scine_utilities`` Python bindings. 60 | A minimal workflow could look like this:: 61 | 62 | import scine_utilities as su 63 | import scine_xtb_wrapper 64 | 65 | # Generate Structure 66 | structure = su.AtomCollection() 67 | structure.elements = [su.ElementType.H, su.ElementType.H] 68 | structure.positions = [[-0.7, 0, 0], [0.7, 0, 0]] 69 | 70 | # Get calculator 71 | manager = su.core.ModuleManager() 72 | calculator = manager.get('calculator', 'GFN2') 73 | 74 | # Configure calculator 75 | calculator.structure = structure 76 | calculator.set_required_properties([su.Property.Energy, su.Property.Gradients]) 77 | 78 | # Calculate 79 | results = calculator.calculate() 80 | print(results.energy) 81 | print(results.gradients) 82 | 83 | How to Cite 84 | ----------- 85 | 86 | When publishing results obtained with SCINE we kindly ask you to cite the 87 | appropriate references, e.g. the one for ReaDuct. 88 | This wrapper does not have its own reference; it should also not be mistaken 89 | for the actual `xtb` code it wraps. 90 | 91 | For the latter code and its citations, we refer you to the original `xtb` 92 | repository. There you will find the references of the actual methods used. 93 | They are listed in the 94 | `README.md `_. 95 | 96 | Support and Contact 97 | ------------------- 98 | 99 | In case you should encounter problems or bugs with the wrapper, please write a 100 | short message to scine@phys.chem.ethz.ch. 101 | 102 | -------------------------------------------------------------------------------- /source/conf.py: -------------------------------------------------------------------------------- 1 | # Configuration file for the Sphinx documentation builder. 2 | # 3 | # This file only contains a selection of the most common options. For a full 4 | # list see the documentation: 5 | # http://www.sphinx-doc.org/en/master/config 6 | 7 | # -- Path setup -------------------------------------------------------------- 8 | 9 | # If extensions (or modules to document with autodoc) are in another directory, 10 | # add these directories to sys.path here. If the directory is relative to the 11 | # documentation root, use os.path.abspath to make it absolute, like shown here. 12 | # 13 | #import os 14 | #import sys 15 | #sys.path.insert(0, os.path.abspath('.')) 16 | 17 | 18 | # -- Project information ----------------------------------------------------- 19 | 20 | project = 'xtb doc' 21 | copyright = '2019-2023, Grimme group' 22 | author = 'Grimme group' 23 | 24 | # The full version, including alpha/beta/rc tags 25 | release = '2023' 26 | 27 | 28 | # -- General configuration --------------------------------------------------- 29 | 30 | # Add any Sphinx extension module names here, as strings. They can be 31 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 32 | # ones. 33 | extensions = [ 34 | "ablog", 35 | "sphinx_design", 36 | "sphinx_copybutton", 37 | "sphinx_togglebutton", 38 | ] 39 | 40 | # Add any paths that contain templates here, relative to this directory. 41 | templates_path = ['_templates'] 42 | 43 | # The language for content autogenerated by Sphinx. Refer to documentation 44 | # for a list of supported languages. 45 | # 46 | # This is also used if you do content translation via gettext catalogs. 47 | # Usually you set "language" from the command line for these cases. 48 | language = 'en' 49 | 50 | # List of patterns, relative to source directory, that match files and 51 | # directories to ignore when looking for source files. 52 | # This pattern also affects html_static_path and html_extra_path. 53 | exclude_patterns = [] 54 | 55 | 56 | # -- Options for HTML output ------------------------------------------------- 57 | 58 | # The theme to use for HTML and HTML Help pages. See the documentation for 59 | # a list of builtin themes. 60 | # 61 | html_theme = 'sphinx_rtd_theme' 62 | 63 | # Add any paths that contain custom static files (such as style sheets) here, 64 | # relative to this directory. They are copied after the builtin static files, 65 | # so a file named "default.css" will overwrite the builtin "default.css". 66 | html_css_files = [ "custom.css", ] 67 | html_static_path = ['_static'] 68 | 69 | # other default 70 | master_doc = 'index' 71 | 72 | # Settings for blog 73 | blog_path = "news" 74 | blog_post_pattern = "_posts/*/*" 75 | post_redirect_refresh = 1 76 | post_auto_image = 1 77 | post_auto_excerpt = 2 78 | -------------------------------------------------------------------------------- /source/crestxmpl.rst: -------------------------------------------------------------------------------- 1 | .. _crest: 2 | 3 | ---------------------------- 4 | CREST documentation 5 | ---------------------------- 6 | 7 | .. contents:: 8 | 9 | Conformer-Rotamer Ensemble Sampling Tool 10 | ========================================== 11 | 12 | CREST is an application program based on the xTB methods. 13 | 14 | The main publication for the CREST program can be found at `Phys. Chem. Chem. Phys., 2020, 22, 7169-7192 `_. 15 | 16 | The documentation of CREST was moved to https://crest-lab.github.io/crest-docs/ 17 | 18 | 19 | -------------------------------------------------------------------------------- /source/dipro.rst: -------------------------------------------------------------------------------- 1 | .. _dipro: 2 | 3 | .. |J(AB)| replace:: :math:`J_{AB}` 4 | .. |J(AB,eff)| replace:: :math:`J_{AB,eff}` 5 | 6 | ------- 7 | DIPRO 8 | ------- 9 | 10 | This guide aimes to give a general overview over the DIPRO implementation within the ``xtb`` program package. 11 | 12 | .. note:: 13 | This feature is only present in the current bleeding-edge version. 14 | 15 | 16 | .. contents:: 17 | 18 | General description 19 | =================== 20 | 21 | The dimer projection method, known as DIPRO (`Andrienko2010 `_), enables the calculation of the electronic coupling integrals between pairs of molecules. DIPRO necessitates three quantum mechanical single-point calculations from any source (e.g., SQM, HF, DFT): one for each monomer (A,B) and another for the dimer (AB), whereas the optimized monomer structures are used in the unrelaxed dimer geometry. The relevant equations are provided below: 22 | 23 | .. math:: 24 | y_1^{i} &= C_{A}^{i} \cdot S_{AB} \cdot C_{AB} 25 | 26 | 27 | y_2^{j} &= C_{B}^{i} \cdot S_{AB} \cdot C_{AB} 28 | 29 | 30 | S_{ab}^{ij} &= y_1^{i} \cdot y_2^{j} 31 | 32 | 33 | J_{ab}^{ij} &= y_1^{i} \cdot E_{AB} \cdot y_2^{j} 34 | 35 | 36 | J_{ab,eff}^{ij} &= | \frac{J_{ab}^{ij} - 0.5 \cdot (E_{A}^{i} + E_{B}^{j}) \cdot S_{ab}^{ij} }{1 - (S_{ab}^{ij})^2} | 37 | 38 | 39 | where :math:`C` are the orbital coefficients, :math:`S` is the AO overlap matrix, :math:`E` are the orbital energies, :math:`i` and :math:`j` denote the molecular orbitals that are considered for the electron or hole transfer. Use the coupling integrals on your way to estimate conductivity and charge transport in materials. 40 | 41 | 42 | Input 43 | ===== 44 | 45 | To perform a DIPRO calculation with ``xtb`` the ``--dipro`` option is used. You can specify a threshold (optional) within which energy range around HOMO and LUMO you want orbitals to be included into the DIPRO run. Default is 0.1 eV. 46 | 47 | .. code:: sh 48 | 49 | > xtb --dipro 0.1 50 | 51 | 52 | Functionality 53 | ============= 54 | 55 | runtype 56 | ------- 57 | 58 | The DIPRO runtype offers similar options like the SCC runtype. Feel free to use solvent, electronic temperature, charge, UHF, method ... as usual. DIPRO is not restartable from ``xtbrestart`` because three singlepoints in a row are performed. 59 | 60 | flags 61 | ----- 62 | 63 | \--chrg 'int': 64 | You can use the classical ``--chrg`` flag to provide the charge for the dimer system. DIPRO will assign it automatically to the individual fragments. An alternative is to provide a .CHRGfrag file and specify the charges for both fragments in the form ``INT INT``. 65 | 66 | \--uhf 'int': 67 | You can use the classical ``--uhf`` flag to provide the number of unpaired electrons for the dimer system. As DIPRO cannot assign it automatically to the individual fragments, you must provide a .UHFfrag file and specify the number of unpaired electrons for both fragments in the form ``INT INT``. 68 | 69 | .. note:: 70 | If .UHFfrag is not given, the calculation will abort. 71 | 72 | xcontrol 73 | -------- 74 | 75 | Although DIPRO offers an automated fragment recognition for NCI fragments, you might need to specify the fragments by hand sometimes. This is possible via the ``xcontrol`` file and the keyword ``$split``. Read in the ``xcontrol`` as usual using ``-I/--input``. 76 | 77 | .. code-block:: none 78 | 79 | $split 80 | fragment1: 1-12,24,25 81 | fragment2: 13-23,26,27 82 | $end 83 | 84 | .. note:: 85 | DIPRO works exclusively with two fragments! At any other number of found fragments the calculation will abort. 86 | 87 | Example: Benzene - Nitrobenzene 88 | ================================ 89 | 90 | This is a very simple example of a cofacial NCI complex of benzene and nitrobenzene. 91 | 92 | .. figure:: ../figures/dipro.png 93 | 94 | .. tab-set:: 95 | 96 | .. tab-item:: cml input 97 | 98 | .. code-block:: none 99 | 100 | > xtb coord.xyz --dipro --gfn 1 101 | 102 | .. tab-item:: input.xyz 103 | 104 | .. code-block:: none 105 | 106 | 26 107 | 108 | C -1.20618 0.69599 1.75211 109 | C -1.20379 -0.70017 1.75215 110 | C 0.00616 -1.39690 1.75210 111 | C 1.21824 -0.70002 1.75171 112 | C 1.23033 0.70989 1.75117 113 | C 0.00125 1.40067 1.75172 114 | H 2.14504 -1.25925 1.74975 115 | H -0.02278 2.48280 1.74976 116 | H -2.14520 1.23405 1.75041 117 | H -2.14028 -1.24255 1.75044 118 | H 0.00554 -2.47919 1.75040 119 | C -1.21072 0.69984 -1.75114 120 | C -1.21074 -0.69902 -1.75149 121 | C 0.00072 -1.39843 -1.75114 122 | C 1.21220 -0.69897 -1.75037 123 | C 1.21222 0.69988 -1.74995 124 | C 0.00077 1.39929 -1.75036 125 | H 2.14941 -1.24008 -1.74839 126 | H 2.14945 1.24099 -1.74755 127 | H 0.00077 2.48148 -1.74837 128 | H -2.14799 1.24091 -1.74971 129 | H -2.14800 -1.24014 -1.75028 130 | H 0.00066 -2.48066 -1.74972 131 | N 2.46723 1.42685 1.74737 132 | O 2.47280 2.62117 1.74468 133 | O 3.50640 0.83800 1.74471 134 | 135 | .. tab-item:: output 136 | 137 | .. code-block:: none 138 | 139 | ------------------------------------------------- 140 | | D I P R O | 141 | ------------------------------------------------- 142 | 143 | Calculation for dimer 144 | --------------------- 145 | . 146 | . 147 | . 148 | Found 2 fragments! 149 | Fragment 1: 1-11, 24-26 150 | Fragment 2: 12-23 151 | 152 | Calculation for fragment 1 153 | ------------------------------ 154 | 155 | charge of fragment : 0 156 | unpaired e- of fragment : 0 157 | . 158 | . 159 | . 160 | 161 | Calculation for fragment 2 162 | ------------------------------ 163 | 164 | charge of fragment : 0 165 | unpaired e- of fragment : 0 166 | . 167 | . 168 | . 169 | 170 | :::::::::::::::::::::::::::::::::::::::::::::: 171 | :: D I P R O C O U P L I N G S :: 172 | :::::::::::::::::::::::::::::::::::::::::::::: 173 | 174 | energy threshhold for near-degenerate orbitals near HOMO and LUMO considered for DIPRO: 0.100 eV 175 | no. of orbitals within energy window of frag 1 2 176 | no. of orbitals within energy window of frag 2 4 177 | 178 | Fragment 1 HOMO Fragment 2 HOMO-1 179 | -------------------------------------- 180 | E_mon(orb) frag1 frag2 -12.966 -12.094 eV 181 | |J(AB)|: 0.001 eV 182 | S(AB): 0.00002581 Eh 183 | |J(AB,eff)|: 0.000 eV 184 | 185 | Fragment 1 HOMO Fragment 2 HOMO 186 | -------------------------------------- 187 | E_mon(orb) frag1 frag2 -12.966 -12.099 eV 188 | |J(AB)|: 0.238 eV 189 | S(AB): -0.00998928 Eh 190 | |J(AB,eff)|: 0.113 eV 191 | 192 | Fragment 1 HOMO Fragment 2 LUMO 193 | -------------------------------------- 194 | E_mon(orb) frag1 frag2 -12.966 -7.366 eV 195 | |J(AB)|: 0.002 eV 196 | S(AB): -0.00009192 Eh 197 | |J(AB,eff)|: 0.001 eV 198 | 199 | Fragment 1 HOMO Fragment 2 LUMO+1 200 | ------------------------------------- 201 | E_mon(orb) frag1 frag2 -12.966 -7.361 eV 202 | |J(AB)|: 0.000 eV 203 | S(AB): 0.00001124 Eh 204 | |J(AB,eff)|: 0.000 eV 205 | 206 | Fragment 1 LUMO Fragment 2 HOMO-1 207 | -------------------------------------- 208 | E_mon(orb) frag1 frag2 -9.417 -12.094 eV 209 | |J(AB)|: 0.035 eV 210 | S(AB): -0.00153946 Eh 211 | |J(AB,eff)|: 0.019 eV 212 | . 213 | . 214 | . 215 | 216 | .............................................................................. 217 | : total |J(AB,eff)| for hole transport (occ. MOs) : 0.113 eV : 218 | : total |J(AB,eff)| for charge transport (unocc. MOs) : 0.062 eV : 219 | : total |J(AB,eff)| for charge transfer (CT) : 0.019 eV : 220 | .............................................................................. 221 | 222 | Please remember, DIPRO is not available for restart! 223 | 224 | normal termination of dipro 225 | ---------------------------------------------------------- 226 | * finished run on 2023/08/25 at 16:43:22.737 227 | ---------------------------------------------------------- 228 | dipro: 229 | * wall-time: 0 d, 0 h, 0 min, 0.084 sec 230 | * cpu-time: 0 d, 0 h, 0 min, 0.337 sec 231 | * ratio c/w: 3.996 speedup 232 | 233 | DIPRO first performs a singlepoint calculation on the complex and yields the fragmentation of your input coordinates. 234 | Then, two singlepoint calculations on the fragments structures are performed. 235 | The DIPRO output lists which orbitals from the couplings fragments were considered for the coupling calculations, e.g. the HOMO from fragment 1 (here nitrobenzene) and the HOMO-1 from fragment 2 (here benzene), and their corresponding energies. 236 | The most important parts are the results for the coupling integrals |J(AB)| and |J(AB,eff)|. 237 | Furthermore, a total coupling averaged over the square sum of all individual couplings is printed. 238 | 239 | .. math:: 240 | total |J(AB,eff)| = \sqrt{\sum |J(AB,eff)_i^2|} 241 | 242 | Please find more information on the theory and our implementation of DIPRO in our publication (J.Kohn, N.Gildemeister, D.Fazzi, S.Grimme, A.Hansen, `Efficient Calculation of Electronic Coupling Integrals with the Dimer Projection Method via a Density Matrix Tight-Binding Potential`, JCP **2023**, submitted). 243 | -------------------------------------------------------------------------------- /source/enso_doc/enso.rst: -------------------------------------------------------------------------------- 1 | .. _enso: 2 | 3 | -------------------- 4 | Introduction to ENSO 5 | -------------------- 6 | 7 | .. contents:: 8 | 9 | What is *ENSO* ? 10 | ================ 11 | 12 | `enso` is a utility program to create and refine Conformer, Rotamer-Ensembles and 13 | finally prepare all files necessary to generate NMR spectra using the `anmr` program. 14 | `enso` and additional necessary resources can be found at 15 | `Github ENSO `_ and 16 | `Github Cefine `_. 17 | 18 | The Workflow to get the final spectrum is detailed in the following graphic. 19 | 20 | .. figure:: ../../figures/enso/enso_get_spectrum.png 21 | :scale: 25% 22 | :align: center 23 | :alt: Workflow to get a calculated NMR spectrum 24 | 25 | NMR spectrum calculation workflow. 26 | 27 | 28 | 29 | Short summary 30 | ============= 31 | 32 | The `enso` program is designed to rerank the Conformer Rotamer Ensemble (CRE) 33 | generated by `CREST` (Conformer Rotamer Ensemble Search Tool) at DFT level and 34 | perform subsequent NMR-property calculations. `enso` interfaces to different QM-CODES 35 | (`TURBOMOLE`, `ORCA`, `xtb`) and processes the data. 36 | The *ENSO* is subdivided into four parts. 37 | 38 | .. figure:: ../../figures/enso/enso-short.png 39 | :scale: 30 % 40 | :align: center 41 | :alt: short ENSO description 42 | 43 | *ENSO* flowchart. 44 | 45 | 46 | In *part1* crude optimizations are performed at DFT level. Because of crude thresholds 47 | only a very small number of optimization cycles are perfomed at DFT level, 48 | and the upside is that bondlength are more or less correct. 49 | All geometries with a corresponding DFT energy below an energy thresold (*thr-part1*) 50 | are considered for the full optimization in *part2*. 51 | 52 | In *part2* the structures are fully optimized at DFT level. On these optimized 53 | geometries solvation contributions and thermostatistical contributions to free energy 54 | are calculated. The free energy is obtained as the sum of the 'low-level' 55 | DFT energy :math:`E`, :math:`G_{RRHO}` (thermostatistical contribution to free energy) and 56 | :math:`δG_{solv}` (optional solvation contribution to free energy). Using a second 57 | threshold (this time a free energy based threshold) only conformers with a free energy 58 | below the threshold are considered for the final free energy evaluation in *part3*. 59 | 60 | In *part3* the 'high-level' free energy calculations are performed by calculating 61 | high level DFT single-point energies and recalculating the free energy. At this stage 62 | Boltzmann weights for the remaining conformers are calculated. All conformers with a 63 | Boltzmann contribution below 1% are neglected and the Bolzmann weights are recalculated. 64 | The Boltzmann weights are summed up to 98% and all conformers within these 98% are 65 | considered for the NMR property calculations. 66 | 67 | In *part4* the couplings and shieldings calculations are performed. Additionally 68 | all information which is required by `anmr` is written by the `enso`. 69 | 70 | After refining the *CREST*-ensemble at DFT level and performing the NMR property 71 | calculations, `anmr` correctly averages the shifts and solves the spin hamiltonian 72 | for the final spectrum generation. 73 | Then `anmr` generates a file 'anmr.dat' which can be plotted to visualize the final spectrum. 74 | 75 | 76 | Getting started 77 | =============== 78 | 79 | To perform an *ENSO* calculation first run: 80 | 81 | .. code:: sh 82 | 83 | ./enso.py [-options] 84 | 85 | This generates a 'flags.dat' configuration file which stores most information 86 | relevant to *ENSO*. 87 | 88 | .. code:: sh 89 | 90 | vim flags.dat # adjust and save the settings in the configuration file to your needs. 91 | 92 | After adjusting the settings in the 'flags.dat', the input can be automatically 93 | checked (for typos and setting-combinations) by `enso`. This way settings or 94 | combinations of settings which are not possible are detected before you actually 95 | start the program. 96 | The check is performed with: 97 | 98 | .. code:: sh 99 | 100 | ./enso.py --checkinput 101 | 102 | When the input is correct the program can be started by typing: 103 | 104 | .. code:: sh 105 | 106 | export PYTHONUNBUFFERED=1 107 | ./enso.py --run > enso.out 2> enso.error & 108 | 109 | To save the output of `enso` it is necessary to pipe the output into a file. 110 | Using this `export PYTHONUNBUFFERED=1` the progress of the calculations can be 111 | tracked immediatly and the user doesn't need to wait until the python buffer is 112 | written to the file. For the program to work correctly the information of the 113 | absolute paths to the programs employed in ``ENSO`` has to be available in the 114 | global configuration file *.ensorc*. 115 | 116 | 117 | 118 | 119 | -------------------------------------------------------------------------------- /source/enso_doc/enso_anmr.rst: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | ==== 5 | ANMR 6 | ==== 7 | 8 | ``ANMR`` requires the files: 9 | 10 | * *coord*, turbomole data group 11 | * anmr_nucinfo (human readable), written by `crest` 12 | 13 | * information on which nuclei can interchange in your molecule (e.g. the hydrogen 14 | atoms in a methlygroup) 15 | * = information on chemical and magnetical equivalent atoms 16 | * anmr_rotamer (machine readable), written by `crest` 17 | 18 | * information on the rotamers detected by `crest` 19 | * anmr_enso, written by `enso` 20 | 21 | * information on the contributing conformers, the Boltzmann weight and all 22 | contributions to free energy 23 | * .anmrrc, written by `enso` 24 | 25 | * `anmr` searches for the *.anmrrc* file first in the folder of execution and 26 | if not found in the home directory of the user 27 | * The file contains the reference-shieldings of e.g TMS to convert the calculated 28 | shielding to shifts 29 | * the folders with the property calculations of the conformers 30 | 31 | * e.g. CONF1/NMR 32 | 33 | 34 | Example **.anmrrc** file: 35 | 36 | .. code:: 37 | 38 | 7 8 XH acid atoms 39 | ENSO qm= TM mf= 300 lw= 1.0 J= on S= on 40 | TMS[chcl3] pbe0[COSMO]/def2-TZVP//pbeh-3c[DCOSMO-RS]/def2-mSVP 41 | 1 31.786 0.0 1 42 | 6 189.674 0.0 0 43 | 9 182.57 0.0 0 44 | 15 291.9 0.0 0 45 | 46 | The first line in .anmrrc informs `anmr` to ignore all protons bound to nitrogen 47 | (N=7) and oxygen (O=8). If you want to calculate protons bound to oxygen or nitrogen, 48 | simply remove the corresponding number, but leave the rest of the line intact! 49 | The next line starting with *ENSO* informs ``ANMR`` that the property calculation 50 | was performed by *TM* = TURBOMOLE (or *ORCA* = ORCA). The *mf=* 300 informs ``ANMR`` 51 | that the magnetic frequency of the NMR spectrometer is set to 300 MHz. The *lw* 52 | (linewidth for plotting) is 1.0 and J (couplings) and S (shieldings) are to be evaluated. 53 | If *S=* off then ``ANMR`` will terminate after calculating and averaging the shifts of the 54 | molecule under consideration. The next line explains how the reference shieldings are 55 | calculated: in this case the reference molecule is tetramethylsilane in chloroform and the 56 | shielding is calculated with PBE0/def2-TZVP + COSMO on PBEh-3c + DCOSMO-RS geometries. 57 | 58 | The following lines contain the data on **[atomic number]** **[calculated shielding valule 59 | of the reference molecule]** **[experimental shift]** **[active or not]**. 60 | 61 | The lines show the reference shieldings for hydrogen (1), carbon (6) fluor (9) and 62 | phosphorus (15). The third number within the last four lines is 0.0 and can be used to adjust 63 | the shift of the reference (e.g. to the experimental shift). 64 | The last number in the last four lines can either be 1 or 0 and this 65 | switches the 'element on or off' for the spectrum calculation. 66 | 67 | Example **anmr_enso** file: 68 | 69 | .. code:: 70 | 71 | ONOFF NMR CONF BW Energy Gsolv RRHO 72 | 1 1 1 0.10042 -354.38939 -0.00899 0.22109 73 | 1 2 2 0.32452 -354.39034 -0.00899 0.22093 74 | 1 3 3 0.57506 -354.39287 -0.00902 0.22295 75 | 76 | The file *anmr_enso* is written by the `enso` program and contains information on 77 | the conformers, which folder they are in, the Boltzmann weight, energy, solvation 78 | and thermostatistical contribution to free energy. The first number in the three last 79 | lines indicates to ``ANMR`` if the conformer is to be considered (1) or not (0). 80 | If one conformer is not considered (or more) `anmr` program internally recalculates 81 | the Boltzmann weights based on the free energies from the *anmr_enso* file. 82 | 83 | 84 | Usage of `anmr`: 85 | 86 | First of all: the spin problem is of :math:`2^{N}` complexity! Depending on the 87 | size of the maximalspinsystem (*mss*) the program might use a lot of RAM! 88 | If this is the case, run `anmr` with a decreased spinsystem size: 89 | 90 | 91 | .. code:: sh 92 | 93 | anmr -mss 12 > anmr.out 2> anmr.error & 94 | 95 | 96 | `anmr` will then write a file called *anmr.dat* (which is quiet large). The file 97 | contains the information ppm vs intesity. This file can then be plotted with any 98 | plotting tool or our 'nmrplot.py'. 99 | 100 | To reduce the large size of the file you can remove entries which are close to 101 | zero with either this awk or python code: 102 | 103 | .. code-block:: sh 104 | 105 | head -1 anmr.dat > newanmr.dat 106 | awk '($2 > 0.001){print $0}' anmr.dat >> newanmr.dat 107 | tail -1 anmr.dat >> newanmr.dat 108 | 109 | .. code-block:: python3 110 | 111 | import numpy as np 112 | data = np.genfromtxt('anmr.dat') 113 | threshold = 0.001 114 | data2 = data[np.logical_not(data[:,1] < threshold)] 115 | data2 = np.insert(data2, 0, (data[0][0], threshold), axis=0) 116 | data2 = np.insert(data2, len(data2), (data[-1][0], threshold), axis=0) 117 | np.savetxt('newanmr.dat', data2, fmt='%2.5e' ) 118 | -------------------------------------------------------------------------------- /source/enso_doc/plotting.rst: -------------------------------------------------------------------------------- 1 | ================ 2 | Spectra Plotting 3 | ================ 4 | 5 | The NMR spectrum can be plotted from the file `anmr.dat`. It contains the 6 | information ppm vs intensity and can be plotted with any plotting tool 7 | (e.g GNUPLOT ...). 8 | 9 | The provided `nmrplot.py` plotting tool uses `matplotlib` for plotting. 10 | Information on all possible commandline arguments is documented: 11 | 12 | .. code-block:: text 13 | 14 | > nmrplot.py --help 15 | 16 | __________________________________________________ 17 | | | 18 | | NMRPLOT | 19 | | Plotting of NMR spectral data | 20 | | University of Bonn, MCTC | 21 | | January 2019 | 22 | | v 1.05 | 23 | | F. Bohle | 24 | |__________________________________________________| 25 | 26 | Information on arguments: 27 | 28 | End Endremove Startremove Start 29 | + + + + 30 | +---------------+----+-------------------------------+ 31 | lower field higher field 32 | delta /ppm 33 | 34 | optional arguments: 35 | -h, --help show this help message and exit 36 | -start START, --startppm START 37 | Start plotting from '' ppm. (default: 0) 38 | -end END, --endppm END 39 | End plotting at '' ppm. Value of end has to be 40 | larger than value of start. (default: 11) 41 | -startremove STARTREMOVE, --startremove STARTREMOVE 42 | Start cutting from spectrum at '' ppm. 43 | (default: None) 44 | -endremove ENDREMOVE, --endremove ENDREMOVE 45 | End cutting from spectrum at '' ppm. Value 46 | of endremove has to be larger than value of 47 | startremove. (default: None) 48 | -title TITLE, --title TITLE 49 | Set title of entire plot. If no title is required use 50 | '<--title ''>'. (default: NMR-PLOT) 51 | -lw LINEWIDTH, --linewidth LINEWIDTH 52 | Set linewidth. (default: 0.8) 53 | -i FILE [FILE ...], --input FILE [FILE ...] 54 | Provide input_file(s) [max 3 files] -i input1(theory1) 55 | input2(theory2) input3(experiment/predicition); 56 | inputfiles format is two columns: column1 ppm , 57 | column2 intensity; if several files are provided the 58 | last one will be inverted (default: None) 59 | -l LABEL [LABEL ...], --label LABEL [LABEL ...] 60 | Provide labels for all files provided [max 3 files] -l 61 | label1 label2 label3, if no labels are provided, 62 | filename is used as label (default: []) 63 | -fontsize FONTSIZE, --fontsize FONTSIZE 64 | Set fontsize for entire plot. (default: 15) 65 | -keybox, --keybox Set Frame around key. (default: False) 66 | -ontop, --ontop Plot all spectra ontop of each other. (default: False) 67 | -stacked, --stacked Plot all spectra stacked over each other. (default: 68 | False) 69 | -orientation ORIENTATION [ORIENTATION ...], --orientation ORIENTATION [ORIENTATION ...] 70 | Up (1) or down (-1). (default: [1, 1, 1, 1, 1, 1, 1, 71 | 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]) 72 | -c [ ...], --colors [ ...] 73 | Select colors. Possible are: ['gray', 'blue', 'cyan', 74 | 'red', 'green', 'magenta', 'yellow', 'black'] 75 | (default: ['blue', 'black', 'red', 'magenta', 76 | 'green']) 77 | -cut CUT [CUT ...], --cut CUT [CUT ...] 78 | Cut intensity. Accepts values from 0.0 (flat line) to 79 | 1.0 (full intensity). (default: [1.0, 1.0, 1.0, 1.0, 80 | 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0]) 81 | -o OUT, --output OUT Provide name of the output file without fileending. 82 | (default: nmrplot) 83 | -s SHIFT [SHIFT ...], --shift SHIFT [SHIFT ...] 84 | Shift ppm of each inputfile separately using: --shift 85 | float float float, e.g. --shift 10.0 0.0 -5.0, each 86 | file needs its own value (default: []) 87 | -------------------------------------------------------------------------------- /source/gbsa.rst: -------------------------------------------------------------------------------- 1 | .. _gbsa: 2 | 3 | -------------------- 4 | Implicit Solvation 5 | -------------------- 6 | 7 | In this chapter, all neccessary information will be given in order 8 | to use the implicit solvent model ALPB in xTB calculations. 9 | Parameterized solvents and available grids are given as well. 10 | 11 | .. contents:: 12 | 13 | General command-line control 14 | ============================ 15 | 16 | .. note:: 17 | 18 | The ALPB solvation model is implemented in version 6.3.3 or newer, use ``--gbsa`` in older versions instead. 19 | 20 | The analytical linearized Poisson-Boltzmann (ALPB) model is envoked with the flag ``--alpb [Solvent]``. 21 | As an example the single point calculation employing the ALPB model for solvation in water would be started by 22 | 23 | .. code:: bash 24 | 25 | > xtb coord --alpb water 26 | 27 | As an example the energy printout of a singlepoint calculation of a H₂O molecule in implicit water is given. 28 | 29 | .. code:: bash 30 | 31 | ::::::::::::::::::::::::::::::::::::::::::::::::::::: 32 | :: SUMMARY :: 33 | ::::::::::::::::::::::::::::::::::::::::::::::::::::: 34 | :: total energy -5.080125650447 Eh :: 35 | :: total w/o Gsasa/hb -5.072630011432 Eh :: 36 | :: gradient norm 0.000116027126 Eh/a0 :: 37 | :: HOMO-LUMO gap 14.677994988515 eV :: 38 | ::.................................................:: 39 | :: SCC energy -5.114015528669 Eh :: 40 | :: -> isotropic ES 0.042942180411 Eh :: 41 | :: -> anisotropic ES -0.000536031457 Eh :: 42 | :: -> anisotropic XC -0.000425709023 Eh :: 43 | :: -> dispersion -0.000131265012 Eh :: 44 | :: -> Gsolv -0.011732627293 Eh :: 45 | :: -> Gelec -0.004236988278 Eh :: 46 | :: -> Gsasa 0.000208166036 Eh :: 47 | :: -> Ghb -0.009561248178 Eh :: 48 | :: -> Gshift 0.001857443127 Eh :: 49 | :: repulsion energy 0.033889878222 Eh :: 50 | :: add. restraining 0.000000000000 Eh :: 51 | :: total charge 0.000000000000 e :: 52 | ::::::::::::::::::::::::::::::::::::::::::::::::::::: 53 | 54 | 55 | The solvation free energy is printed as ``Gsolv`` and is also added 56 | to all total energy printouts. 57 | 58 | Optimizing a geometry with the ALPB model can be done with the following input 59 | 60 | .. code:: bash 61 | 62 | > xtb coord --opt --alpb water 63 | 64 | The order of the flags can be altered and the input 65 | is not case sensitive. 66 | Like in a optimization without ALPB the optimized coordinates are 67 | written to a new file (``xtbopt.coord``). 68 | In General the ALPB can be used in combination with all available run types 69 | implemented in the `xtb`. 70 | 71 | Parameterized Solvents 72 | ====================== 73 | 74 | The ALPB model is parameterized for the Hamiltonian of GFN1-xTB, GFN2-xTB, and the GFN-FF, but not for GFN0-xTB. 75 | For the GFN1-xTB and GFN2-xTB Hamltonians also a generalized Born (GB) model with surface area (SA) contributions, dubbed GBSA is available. 76 | Here is a list of the available solvents. 77 | 78 | =============== ============ ============ ============ ============ ======== 79 | solvents GFN1(ALPB) GFN1(GBSA) GFN2(ALPB) GFN2(GBSA) GFN-FF 80 | =============== ============ ============ ============ ============ ======== 81 | Acetone x x x x x 82 | Acetonitrile x x x x x 83 | Aniline x x x 84 | Benzaldehyde x x x 85 | Benzene x x x x x 86 | CH₂Cl₂ x x x x x 87 | CHCl₃ x x x x x 88 | CS₂ x x x x x 89 | Dioxane x x x 90 | DMF x x x x 91 | DMSO x x x x x 92 | Ether x x x x x 93 | Ethylacetate x x x 94 | Furane x x x 95 | Hexadecane x x x 96 | Hexane x x x x 97 | Methanol x x x x x 98 | Nitromethane x x x 99 | Octanol x x x 100 | Octanol (wet) x x x 101 | Phenol x x x 102 | Toluene x x x x x 103 | THF x x x x x 104 | Water (H₂O) x x x x x 105 | =============== ============ ============ ============ ============ ======== 106 | 107 | To get the legacy GBSA model setup a detailed input with 108 | 109 | .. code-block:: text 110 | 111 | $gbsa 112 | kernel=still 113 | 114 | and invoke the program with the ``--gbsa`` flag instead of the ``--alpb`` flag. 115 | 116 | 117 | Available Grids 118 | =============== 119 | 120 | Different Lebedev grids for the calculation of the SASA term are 121 | implemented in ``xtb``. The grids are independent of the used GFNn method 122 | and are set in the detailed input as 123 | 124 | .. code-block:: text 125 | 126 | $gbsa 127 | gbsagrid=tight 128 | 129 | 130 | The default grid level is ``normal``. 131 | The available grid levels are given in the table below 132 | with the corresponding number of gridpoints. 133 | 134 | +---------------+--------------+ 135 | | Gridlevel | Gridpoints | 136 | +===============+==============+ 137 | | normal | 230 | 138 | +---------------+--------------+ 139 | | tight | 974 | 140 | +---------------+--------------+ 141 | | verytight | 2030 | 142 | +---------------+--------------+ 143 | | extreme | 5810 | 144 | +---------------+--------------+ 145 | 146 | Larger grids increase the computation time and 147 | reduce numerical noise in the energy. They may help to converge 148 | geometry optimizations with ALPB for large molecules which 149 | would otherwise not converge due to numerical noise. 150 | 151 | Reference States 152 | ================ 153 | 154 | For solvation free energies, the state of the inital gas and final liquid solution can be changed with a solution state correction. 155 | This is explained in detail in the following table and in [A Universal pH Scale for All Solvents: Background, Theory, and Justification (IUPAC Technical Report)](https://doi.org/10.1515/pac-2019-0504), section 2.2. 156 | By default no solution state correction is applied (gsolv, default), which is comparable with most other solvation models (SMD, COSMO-RS, ...). 157 | For normal production runs, the option ``bar1mol`` should be used. For explicit comparisons with ``reference`` state corrected COSMO-RS, the ``reference`` option should be used (includes solvent-specific correction for infinite dilution). 158 | Solution state correction is available for the ALPB and GBSA solvation models. 159 | 160 | ================== ==================================================================== 161 | Name Definition 162 | ================== ==================================================================== 163 | gsolv (default) 1 L of ideal gas and 1 L of liquid solution 164 | bar1mol 1 bar of ideal gas and 1 mol/L liquid solution 165 | reference 1 bar of ideal gas and 1 mol/L liquid solution at infinite dilution 166 | ================== ==================================================================== 167 | 168 | The reference state can be set via 169 | .. code:: bash 170 | 171 | xtb coord --opt --alpb water reference 172 | 173 | Extended Functionality 174 | ====================== 175 | 176 | Solvent Accessable Surface Area 177 | ------------------------------- 178 | 179 | .. note:: feature implemented in version 6.2 180 | 181 | To get more insights and diagnostics for a ALPB calculation the Born radii 182 | and the solvent accessable surface area can be printed by toggling the 183 | property-printout with 184 | 185 | .. code-block:: none 186 | 187 | $write 188 | gbsa=true 189 | 190 | The printout for a branched octane isomer using ALPB(Water) looks like 191 | 192 | .. code-block:: none 193 | 194 | * generalized Born model for continuum solvation 195 | 196 | # Z Born rad/Å SASA/Ų H-bond 197 | 1 6 C 3.761 0.000 0.000 198 | 2 6 C 3.761 0.000 0.000 199 | 3 6 C 2.741 1.820 -0.000 200 | 4 6 C 2.741 1.839 -0.000 201 | 5 6 C 2.741 1.817 -0.000 202 | 6 6 C 2.741 1.820 -0.000 203 | 7 6 C 2.741 1.839 -0.000 204 | 8 6 C 2.741 1.817 -0.000 205 | 9 1 H 2.136 11.404 -0.015 206 | 10 1 H 2.130 12.571 -0.017 207 | 11 1 H 2.098 14.966 -0.020 208 | 12 1 H 2.130 12.563 -0.017 209 | 13 1 H 2.098 14.979 -0.020 210 | 14 1 H 2.136 11.403 -0.015 211 | 15 1 H 2.136 11.412 -0.015 212 | 16 1 H 2.130 12.524 -0.017 213 | 17 1 H 2.098 14.948 -0.020 214 | 18 1 H 2.136 11.404 -0.015 215 | 19 1 H 2.130 12.571 -0.017 216 | 20 1 H 2.098 14.966 -0.020 217 | 21 1 H 2.130 12.563 -0.017 218 | 22 1 H 2.098 14.979 -0.020 219 | 23 1 H 2.136 11.403 -0.015 220 | 24 1 H 2.136 11.412 -0.015 221 | 25 1 H 2.130 12.524 -0.017 222 | 26 1 H 2.098 14.948 -0.020 223 | 224 | total SASA / Ų : 244.491 225 | 226 | The quartary carbon atoms are shown with no solvent accessable surface area, 227 | which means they are completely buried in the molecule leading to large 228 | Born radii. 229 | -------------------------------------------------------------------------------- /source/help.rst: -------------------------------------------------------------------------------- 1 | Need Help 2 | ========= 3 | 4 | If you're heading trouble please contact xtb@thch.uni-bonn.de 5 | 6 | -------------------------------------------------------------------------------- /source/hidden_code_block.py: -------------------------------------------------------------------------------- 1 | """Simple, inelegant Sphinx extension which adds a directive for a 2 | highlighted code-block that may be toggled hidden and shown in HTML. 3 | This is possibly useful for teaching courses. 4 | 5 | The directive, like the standard code-block directive, takes 6 | a language argument and an optional linenos parameter. The 7 | hidden-code-block adds starthidden and label as optional 8 | parameters. 9 | 10 | Examples: 11 | 12 | .. hidden-code-block:: python 13 | :starthidden: False 14 | 15 | a = 10 16 | b = a + 5 17 | 18 | .. hidden-code-block:: python 19 | :label: --- SHOW/HIDE --- 20 | 21 | x = 10 22 | y = x + 5 23 | 24 | Thanks to http://www.javascriptkit.com/javatutors/dom3.shtml for 25 | inspiration on the javascript. 26 | 27 | Thanks to Milad 'animal' Fatenejad for suggesting this extension 28 | in the first place. 29 | 30 | Written by Anthony 'el Scopz' Scopatz, January 2012. 31 | 32 | Released under the WTFPL (http://sam.zoy.org/wtfpl/). 33 | """ 34 | 35 | from docutils import nodes 36 | from docutils.parsers.rst import directives 37 | from sphinx.directives.code import CodeBlock 38 | 39 | HCB_COUNTER = 0 40 | 41 | js_showhide = """\ 42 | 53 | """ 54 | 55 | def nice_bool(arg): 56 | tvalues = ('true', 't', 'yes', 'y') 57 | fvalues = ('false', 'f', 'no', 'n') 58 | arg = directives.choice(arg, tvalues + fvalues) 59 | return arg in tvalues 60 | 61 | 62 | class hidden_code_block(nodes.General, nodes.FixedTextElement): 63 | pass 64 | 65 | 66 | class HiddenCodeBlock(CodeBlock): 67 | """Hidden code block is Hidden""" 68 | 69 | option_spec = dict(starthidden=nice_bool, 70 | label=str, 71 | **CodeBlock.option_spec) 72 | 73 | def run(self): 74 | # Body of the method is more or less copied from CodeBlock 75 | code = u'\n'.join(self.content) 76 | hcb = hidden_code_block(code, code) 77 | hcb['language'] = self.arguments[0] 78 | hcb['linenos'] = 'linenos' in self.options 79 | hcb['starthidden'] = self.options.get('starthidden', True) 80 | hcb['label'] = self.options.get('label', '+ show/hide code') 81 | hcb.line = self.lineno 82 | return [hcb] 83 | 84 | 85 | def visit_hcb_html(self, node): 86 | """Visit hidden code block""" 87 | global HCB_COUNTER 88 | HCB_COUNTER += 1 89 | 90 | # We want to use the original highlighter so that we don't 91 | # have to reimplement it. However it raises a SkipNode 92 | # error at the end of the function call. Thus we intercept 93 | # it and raise it again later. 94 | try: 95 | self.visit_literal_block(node) 96 | except nodes.SkipNode: 97 | pass 98 | 99 | # The last element of the body should be the literal code 100 | # block that was just made. 101 | code_block = self.body[-1] 102 | 103 | fill_header = {'divname': 'hiddencodeblock{0}'.format(HCB_COUNTER), 104 | 'startdisplay': 'none' if node['starthidden'] else 'block', 105 | 'label': node.get('label'), 106 | } 107 | 108 | divheader = ("""""" 109 | """{label}
""" 110 | '''
''' 111 | ).format(**fill_header) 112 | 113 | code_block = js_showhide + divheader + code_block + "
" 114 | 115 | # reassign and exit 116 | self.body[-1] = code_block 117 | raise nodes.SkipNode 118 | 119 | 120 | def depart_hcb_html(self, node): 121 | """Depart hidden code block""" 122 | # Stub because of SkipNode in visit 123 | 124 | 125 | def setup(app): 126 | app.add_directive('hidden-code-block', HiddenCodeBlock) 127 | app.add_node(hidden_code_block, html=(visit_hcb_html, depart_hcb_html)) 128 | -------------------------------------------------------------------------------- /source/index.rst: -------------------------------------------------------------------------------- 1 | ============================================== 2 | User Guide to Semiempirical Tight Binding 3 | ============================================== 4 | 5 | This user guide focuses on the semiempirical quantum mechanical methods GFNn-xTB, 6 | their descendants, and corresponding composite schemes as implemented in the 7 | `xtb `_ (extended tight binding) program package. 8 | 9 | We provide a number of detailed guides dealing with common tasks that can 10 | be performed easily with the ``xtb`` program. 11 | All guides are usually structured the same way, starting with some simple 12 | examples using only the command line and the default settings, followed 13 | by a troubleshooting section. 14 | Detailed inputs are provided in a ready-to-use fashion to solve some 15 | more special but still common tasks with ``xtb`` together with some 16 | insights into the theory used behind the scenes. 17 | 18 | 19 | ------------- 20 | Quick Links 21 | ------------- 22 | 23 | .. figure:: https://github.com/awvwgk/xtb-logo/raw/master/xtb.svg 24 | :width: 25% 25 | :alt: xtb 26 | :align: center 27 | 28 | `Documentation for xtb `_ 29 | 30 | .. figure:: https://github.com/grimme-lab/crest/raw/master/assets/crest.png 31 | :width: 25% 32 | :alt: CREST 33 | :align: center 34 | 35 | `Documentation for CREST `_ 36 | 37 | .. figure:: ../figures/CENSO/censo_logo_300dpi.png 38 | :width: 25% 39 | :alt: CENSO 40 | :align: center 41 | 42 | `Documentation for CENSO `_ 43 | 44 | .. figure:: ../figures/qcxms/qcxms_logo.svg 45 | :width: 25% 46 | :alt: QCxMS 47 | :align: center 48 | 49 | `Documentation for QCxMS `_ 50 | 51 | 52 | .. figure:: ../figures/qcxms2/qcxms2_logo.svg 53 | :width: 25% 54 | :alt: QCxMS2 55 | :align: center 56 | 57 | `Documentation for QCxMS2 `_ 58 | 59 | .. figure:: ../logo/logo_abtgrimme_desktop.png 60 | :width: 25% 61 | :alt: Grimme-lab 62 | :align: center 63 | 64 | `Explore on GitHub `_ 65 | 66 | -------------------------------------------- 67 | Recent developments, news, and publications 68 | -------------------------------------------- 69 | 70 | .. postlist:: 5 71 | :date: %Y-%m-%d 72 | :format: {date}: {title} by {author} 73 | :excerpts: 74 | 75 | See the :ref:`news archive ` for all posts. 76 | 77 | ----------------------------------------- 78 | xTB in Other Quantum Chemistry Programs 79 | ----------------------------------------- 80 | 81 | The xTB-methods are now officially available in other quantum chemistry programs! 82 | 83 | - in `Orca`_ 4.2 an IO-based interface to the ``xtb`` binary is available 84 | - `AMS`_ 2019 implements GFN1-xTB in their DFTB module 85 | - the `entos`_ program implements GFN1-xTB (also available in the web interface) 86 | - the computational chemistry framework `cuby4`_ supports ``xtb`` 87 | - `Turbomole`_ does support GFN1-xTB and GFN2-xTB since version 7.4 88 | - `QCEngine`_ supports calculations with the ``xtb`` API 89 | - the `GMIN`_, `OPTIM`_, and `PATHSAMPLE`_ global optimization tools provide an ``xtb`` interface 90 | - `CP2K`_ has a GFN1-xTB implementation since version 7.1 91 | - `DFTB+`_ support GFN1-xTB and GFN2-xTB since version 21.2 92 | 93 | .. _Orca: https://orcaforum.kofo.mpg.de 94 | .. _AMS: https://www.scm.com/product/dftb/ 95 | .. _entos: https://www.entos.info/ 96 | .. _cuby4: http://cuby4.molecular.cz/interface_xtb.html 97 | .. _Turbomole: https://www.turbomole.org/ 98 | .. _QCEngine: http://docs.qcarchive.molssi.org/projects/QCEngine 99 | .. _GMIN: http://www-wales.ch.cam.ac.uk/examples/GMIN 100 | .. _OPTIM: http://www-wales.ch.cam.ac.uk/OPTIM 101 | .. _PATHSAMPLE: http://www-wales.ch.cam.ac.uk/PATHSAMPLE/ 102 | .. _CP2K: https://www.cp2k.org/version_history 103 | .. _DFTB+: https://www.dftbplus.org/ 104 | 105 | We missed your project here? 106 | No problem, just give us a hint at the mailing list or open an issue at `GitHub`_. 107 | 108 | .. _GitHub: https://github.com/grimme-lab/xtb_docs/issues/new 109 | 110 | 111 | .. toctree:: 112 | :maxdepth: 3 113 | :caption: Quickstart 114 | 115 | setup 116 | basics 117 | commandline 118 | geometry 119 | xcontrol 120 | development 121 | 122 | .. toctree:: 123 | :maxdepth: 3 124 | :caption: Guides 125 | 126 | sp 127 | properties 128 | optimization 129 | scan 130 | gbsa 131 | hessian 132 | md 133 | mtd 134 | oniom 135 | dipro 136 | path 137 | gsm 138 | periodic_boundary_conditions 139 | pcem 140 | gfnff 141 | ptb 142 | spgfn 143 | capi 144 | python 145 | community/index 146 | 147 | .. toctree:: 148 | :maxdepth: 3 149 | :caption: Submodules 150 | 151 | xtb_info 152 | xtb_docking 153 | xtb_thermo 154 | xtb_ir 155 | xtb_topo 156 | 157 | .. toctree:: 158 | :maxdepth: 3 159 | :caption: CREST 160 | 161 | crestxmpl 162 | 163 | .. toctree:: 164 | :maxdepth: 3 165 | :caption: ENSO 166 | 167 | enso_doc/enso 168 | enso_doc/enso_setup 169 | enso_doc/enso_usage 170 | enso_doc/enso_anmr 171 | enso_doc/plotting 172 | 173 | 174 | .. toctree:: 175 | :maxdepth: 3 176 | :caption: CENSO 177 | 178 | CENSO_docs/censo 179 | CENSO_docs/censorc 180 | CENSO_docs/censo_nmr 181 | CENSO_docs/abbreviations 182 | CENSO_docs/censo_extensive_keywords 183 | CENSO_docs/censo_parallel 184 | CENSO_docs/censo_implementation 185 | 186 | .. toctree:: 187 | :maxdepth: 3 188 | :caption: QCxMS 189 | 190 | qcxms_doc/qcxms 191 | qcxms_doc/qcxms_setup 192 | qcxms_doc/qcxms_run 193 | qcxms_doc/qcxms_plot 194 | qcxms_doc/qcxms_ex 195 | qcxms_doc/qcxms_cites 196 | 197 | .. toctree:: 198 | :maxdepth: 3 199 | :caption: QCxMS2 200 | 201 | qcxms2_doc/qcxms2 202 | qcxms2_doc/qcxms2_setup 203 | qcxms2_doc/qcxms2_run 204 | qcxms2_doc/qcxms2_plot 205 | qcxms2_doc/qcxms2_ex 206 | qcxms2_doc/qcxms2_cites 207 | 208 | 209 | .. toctree:: 210 | :maxdepth: 3 211 | :caption: Misc 212 | 213 | news 214 | versions 215 | xtbrelatedrefs 216 | license 217 | help 218 | 219 | -------------------------------------------------------------------------------- /source/license.rst: -------------------------------------------------------------------------------- 1 | License 2 | ======= 3 | 4 | This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International (**CC BY-SA 4.0**). 5 | To view a copy of this license, visit `creative commons `_ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA. 6 | -------------------------------------------------------------------------------- /source/md.rst: -------------------------------------------------------------------------------- 1 | .. _md: 2 | 3 | ------------------------------- 4 | Molecular Dynamics Simulations 5 | ------------------------------- 6 | 7 | In this chapter, all necessary information will be given in order 8 | to perform MD simulations with xTB. 9 | The adjustable parameters will be discussed and a guide to how to change 10 | them will be given. 11 | 12 | .. contents:: 13 | 14 | General command-line control 15 | ============================ 16 | 17 | There are two main possibilities how to evoke a MD simulation. 18 | With the flag ``--omd`` geometry optimization will be performed 19 | and this structure then will be used for the MD simulation, a loose 20 | optimization level will be chosen. 21 | 22 | .. code:: bash 23 | 24 | > xtb coord --omd 25 | 26 | By using the flag ``--md`` the MD simulation will be performed directly with the user given input structure. 27 | 28 | .. code:: bash 29 | 30 | > xtb coord --md 31 | 32 | It is strongly recommended to start the MD simulation from an xTB 33 | optimized structure. 34 | Otherwise there may be instabilities during the MD and the equilibration 35 | will be severely hindered. 36 | 37 | Parameters 38 | ========== 39 | 40 | In order to change the parameters of the MD simulation the ``$md`` block 41 | in the input file has to be modified. 42 | 43 | +---------+---------+-----------+-----------------------------------------+ 44 | | key | value | default | description | 45 | +=========+=========+===========+=========================================+ 46 | | dump | real | 50 fs | interval for trajectory printout | 47 | +---------+---------+-----------+-----------------------------------------+ 48 | | hmass | integer | 4 times | mass of hydrogen atoms | 49 | +---------+---------+-----------+-----------------------------------------+ 50 | | nvt | boolean | true | perform simulation in NVT ensemble | 51 | +---------+---------+-----------+-----------------------------------------+ 52 | | restart | boolean | false | read velocities from ``mdrestart`` | 53 | +---------+---------+-----------+-----------------------------------------+ 54 | | temp | real | 298.15 K | thermostat temperature | 55 | +---------+---------+-----------+-----------------------------------------+ 56 | | time | real | 50 ps | total run time of simulation | 57 | +---------+---------+-----------+-----------------------------------------+ 58 | | sccacc | real | 2.0 | accuracy of xTB calculation in dynamics | 59 | +---------+---------+-----------+-----------------------------------------+ 60 | | shake | integer | 2 | use SHAKE algorithm to constrain bonds | 61 | + + + + + 62 | | | | | 0 = off, 1 = X-H only, 2 = all bonds | 63 | +---------+---------+-----------+-----------------------------------------+ 64 | | step | real | 4 fs | time step for propagation | 65 | +---------+---------+-----------+-----------------------------------------+ 66 | | velo | boolean | false | also write out velocities | 67 | +---------+---------+-----------+-----------------------------------------+ 68 | 69 | The above default setting should look like below in your input file 70 | 71 | .. code:: 72 | 73 | $md 74 | temp=298.15 # in K 75 | time= 50.0 # in ps 76 | dump= 50.0 # in fs 77 | step= 4.0 # in fs 78 | velo=false 79 | nvt =true 80 | hmass=4 81 | shake=2 82 | sccacc=2.0 83 | $end 84 | 85 | .. important :: 86 | For MD simulations with GFN-FF the time step must be reduced, for more information see section :ref:`gfnff` 87 | 88 | MD specific Files 89 | ================= 90 | 91 | After the ``xtb`` program has performed the desired MD simulation the trajectory of the structures can be found in ``xtb.trj``. 92 | Furthermore, files with the names ``scoord.*`` are generated. After every picosecond of simulation the structure at this point will be written into these files. After a successful completion of the MD simulation a ``xtbmdok`` file will be touched. The structure and velocities at the end of the simulation will be written into a ``mdrestart`` file. 93 | 94 | Trajectory 95 | ---------- 96 | The number of structures in the ``xtb.trj`` file depends on the ``dump`` variable and the propagation time step. 97 | For practical purposes the two parameters are converted into a dump frequency *n* = (dump step/time step), e.g., 98 | a structure is written to the trajecotry equidistantly at every *n*-th propagation step. 99 | Due to this conversion the total number of structures in the ``xtb.trj`` file might be slightly larger 100 | than the expected (total runtime/dump step). 101 | The same applies to the ``scoord.*`` files. 102 | 103 | Restart 104 | ------- 105 | The ``mdrestart`` file can be used to restart an MD simulation. The file consists of 6 columns. The initial three columns represent the atom coordinates, followed by their corresponding velocities, both given in atomic units. 106 | Please note that the atoms retain the same order as in the input geometry file. 107 | This can be very helpful for equilibration purposes. 108 | In order to achive this, in the ``$md`` block the ``restart`` parameter has to be set to ``true``. 109 | 110 | .. code:: 111 | 112 | > cat restart.inp 113 | $md 114 | restart=true 115 | 116 | In this case, you will find the **RESTART** printed in the ``xtb`` output. 117 | 118 | Example/Case study 119 | ------------------ 120 | 121 | To summarize the most important topics of this chapter we will perform an MD simulation of the ethane molecule with `xTB`. 122 | Make sure that ``xtb`` is properly set up and you have the following files in your working directory 123 | 124 | .. code:: 125 | 126 | > cat coord 127 | $coord 128 | 1.82409443250962 -0.02380488009596 0.17250251620479 c 129 | 4.68095348739630 -0.02380488009596 0.17250308312263 c 130 | 1.09744635742609 1.41159121722257 -1.12629926294082 h 131 | 1.09744579050825 0.38329239564274 2.06499275150500 h 132 | 1.09744635742609 -1.86629844212581 -0.42118612892243 h 133 | 5.40760175145245 1.81868868193389 0.76619172824984 h 134 | 5.40760212939767 -0.43090215583466 -1.71998734115020 h 135 | 5.40760175145245 -1.45920097741449 1.47130486226824 h 136 | $end 137 | > cat md.inp 138 | $md 139 | time=10 140 | step=1 141 | temp=500 142 | shake=1 143 | 144 | As you can see, we will run the simulation for 10 ps with a timestep of 1 fs at a temperature of 500 Kelvin. Furthermore, all hydrogen-containing bonds will be constrained using the *SHAKE* algorithm. To start the simulation we call xtb as follows 145 | 146 | .. code:: bash 147 | 148 | > xtb coord --input md.inp --omd 149 | 150 | The program will start with performing a geometry optimization, 151 | the optimized structure used to start the dynamic can be found 152 | and inspected in ``xtbopt.coord``. 153 | 154 | In the file ``xtb.trj`` we can find our trajectory. We can analyze the structures now by displaying them in a molecular graphics editor (e.g., `MOLDEN`_, `VMD`_ etc. ) or a trajectory analyzer (e.g. `TRAVIS`_). 155 | 156 | .. _MOLDEN: http://cheminf.cmbi.ru.nl/molden/ 157 | .. _VMD: https://www.ks.uiuc.edu/Research/vmd/ 158 | .. _TRAVIS: https://www.chemie.uni-bonn.de/pctc/mulliken-center/software/travis/travis 159 | 160 | 161 | -------------------------------------------------------------------------------- /source/mtd.rst: -------------------------------------------------------------------------------- 1 | .. _mtd: 2 | 3 | ------------------------------- 4 | Meta-Dynamics Simulations 5 | ------------------------------- 6 | 7 | In this guide, all necessary information will be given in order to perform 8 | meta-dynamics (MTD) simulations with the ``xtb`` program. 9 | For the theory behind our MTD approach please refer to: 10 | 11 | S. Grimme, 12 | *Exploration of Chemical Compound, Conformer, and Reaction Space with 13 | Meta-Dynamics Simulations Based on Tight-Binding Quantum Chemical 14 | Calculations*, 15 | *J. Chem. Theory Comput.*, **2019**, *155*, 2847-2862. 16 | **DOI:** `10.1021/acs.jctc.9b00143`__ 17 | Publication Date (Web): April 3, 2019 18 | 19 | __ https://doi.org/10.1021/acs.jctc.9b00143 20 | 21 | .. contents:: 22 | 23 | From a practical point of view the application of meta-dynamics is quite similar to molecular-dynamic simulations. 24 | In MTD simulations a biasing potential given as a sum of Gaussian functions is additionally expressed. 25 | The root-mean-square deviation (RMSD) in Cartesian space is chosen as a metric for the collective variables. 26 | 27 | All adjustable parameters will be discussed and a guide to how to change them will be given as well as an example. 28 | 29 | General MTD Setup 30 | ================= 31 | 32 | For any MTD calculation a :ref:`detailed-input` file is necessary to enter 33 | the correct calculation mode. The basic parameters for dynamics are taken 34 | from the ``$md`` block as described in the section regarding :ref:`md`. 35 | The ``$metadyn`` data group has to be present in the input file. 36 | All available instructions for this data group are shown here: 37 | 38 | +---------+---------+-----------------------------------------------------------+ 39 | | key | value | description | 40 | +=========+=========+===========================================================+ 41 | | save | integer | maximal number of structures for rmsd criteria | 42 | +---------+---------+-----------------------------------------------------------+ 43 | | kpush | real | scaling factor for rmsd criteria | 44 | +---------+---------+-----------------------------------------------------------+ 45 | | alp | real | width of the gaussian potential used in the rmsd criteria | 46 | +---------+---------+-----------------------------------------------------------+ 47 | | coord | file | external structure file to initialize rmsd criteria | 48 | +---------+---------+-----------------------------------------------------------+ 49 | | atoms | list | atoms to include in the rmsd calculation (default: all) | 50 | +---------+---------+-----------------------------------------------------------+ 51 | 52 | To avoid accidental activation of the bias potential conservative default values 53 | are chosen in the program. So you cannot simply use a commandline-only approach 54 | to perform a MTD calculation. First of all you want to create a ``metadyn.inp`` 55 | file with this content 56 | 57 | .. code:: 58 | 59 | $metadyn 60 | save=10 61 | kpush=1.0 62 | alp=0.2 63 | $end 64 | 65 | You can start the metadynamic calculation now by using the ``--md`` commandline 66 | flag as 67 | 68 | .. code:: bash 69 | 70 | > xtb --md --input metadyn.inp coord 71 | 72 | 73 | By using the flag ``--metadyn integer``, the number of saved structures may 74 | also be entered via the commandline and need not to be present in the 75 | detailed input: 76 | 77 | .. code:: bash 78 | 79 | > xtb --metadyn 10 --input metadyn.inp coord 80 | 81 | MTD specific Files 82 | ------------------ 83 | 84 | After the ``xtb`` program has performed the desired MTD simulation the trajectory of the structures can be found in ``xtb.trj``. 85 | Furthermore, files with the names ``scoord.*`` are generated. After every picosecond of simulation the structure at this point 86 | will be written into these files. After a successful completion of the MTD simulation a ``xtbmdok`` file will be touched. 87 | The structure and velocities at the end of the simulation will be written into a ``mdrestart`` file. 88 | 89 | Restart 90 | ------- 91 | The ``mdrestart`` file can be used to restart an MTD simulation. This can be very helpful for equilibration purposes. 92 | In order to achive this, in the ``$md`` block the ``restart`` parameter has to be set to ``true``. 93 | 94 | .. code:: 95 | 96 | > cat xcontrol 97 | $md 98 | restart=true 99 | 100 | Example/Case study 101 | ================== 102 | 103 | To summarize the most important topics of this chapter we will perform an MTD simulation of the water dimer molecule with `xTB`. 104 | Make sure that ``xtb`` is properly set up and you have the following files in your working directory 105 | 106 | .. code:: 107 | 108 | > cat coord 109 | $coord 110 | -3.41057596145012 0.01397950240733 -2.48858246259228 o 111 | -4.61882519451466 -0.37951683073135 -3.80598534178089 h 112 | -3.93472948277574 1.59474363012965 -1.77520048297923 h 113 | -6.45960866143682 -1.52443579539520 -6.62024481959292 o 114 | -5.26218381176973 -1.40667057754076 -7.97781013203256 h 115 | -6.78373759577982 -3.28799737179945 -6.34039886662289 h 116 | $end 117 | 118 | > cat metadyn.inp 119 | $md 120 | time=10 121 | step=1 122 | temp=298 123 | $end 124 | $metadyn 125 | atoms: 1-3 126 | save=10 127 | kpush=0.02 128 | alp=1.2 129 | $end 130 | 131 | As you can see, we will run the MTD simulation for 10 ps with a timestep of 1 fs at a temperature of 298 Kelvin. 132 | For the meta-dynamics, only the structure of the first water molecule will be taken into account in the rmsd criteria. 133 | To start the simulation we call xtb as follows 134 | 135 | .. code:: bash 136 | 137 | > xtb --md --input metadyn.inp coord 138 | 139 | The output for the example MTD simulation of the water dimer will look like this: 140 | 141 | .. code:: bash 142 | 143 | ------------------------------------------------- 144 | | Meta Dynamics | 145 | ------------------------------------------------- 146 | trajectories on xtb.trj or xtb.trj. 147 | 148 | MD time /ps : 10.00 149 | dt /fs : 1.00 150 | SCC accuracy : 1.00 151 | temperature /K : 298.00 152 | max steps : 10000 153 | block length (av.) : 5000 154 | dumpstep(trj) /fs : 100.00 100 155 | dumpstep(coords)/fs: 1000.00 1000 156 | H atoms mass (amu) : 2 157 | # deg. of freedom : 14 158 | SHAKE on. # bonds : 4 all: T 159 | Berendsen THERMOSTAT on 160 | kpush : 0.020 161 | alpha : 1.200 162 | update : 10 163 | time (ps) Ekin T Etot 164 | 0 0.00 0.00000 0.0198 0. 0. -10.10916 165 | est. speed in wall clock h for 100 ps : 0.01 166 | 200 0.20 -10.09118 0.0116 559. 524. -10.12881 167 | 400 0.40 -10.11436 0.0105 454. 471. -10.13041 168 | 600 0.60 -10.12260 0.0070 431. 316. -10.13157 169 | 800 0.80 -10.12671 0.0071 412. 321. -10.13081 170 | ... ... ... ... ... ... ... 171 | 4800 4.80 -10.13763 0.0084 469. 379. -10.13198 172 | block / : -10.13978 465. drift: 0.99D+02 Tbath : 298. 173 | 5000 5.00 -10.13775 0.0082 465. 368. -10.13253 174 | 5200 5.20 -10.13783 0.0129 469. 582. -10.12808 175 | 5400 5.40 -10.13794 0.0105 471. 474. -10.13014 176 | 5600 5.60 -10.13804 0.0090 470. 407. -10.13140 177 | ... ... ... ... ... ... ... 178 | 9800 9.80 -10.13918 0.0083 462. 376. -10.13258 179 | average properties 180 | Epot : -10.1392169717059 181 | Epot (accurate SCC): -10.1402473210558 182 | Ekin : 1.019492766065306E-002 183 | Etot : -10.1290220440452 184 | T : 459.900938472654 185 | thermostating problem 186 | normal exit of md() 187 | 188 | 189 | In the file ``xtb.trj`` we can find our trajectory. 190 | We can analyze the structures now by displaying them in a molecular graphics editor (e.g., `MOLDEN`_, `VMD`_ etc. ) 191 | or a trajectory analyzer (e.g. `TRAVIS`_). 192 | 193 | .. _MOLDEN: http://cheminf.cmbi.ru.nl/molden/ 194 | .. _VMD: https://www.ks.uiuc.edu/Research/vmd/ 195 | .. _TRAVIS: https://www.chemie.uni-bonn.de/pctc/mulliken-center/software/travis/travis 196 | 197 | Constrained MD/MTD simulations 198 | ============================== 199 | 200 | As you may have noticed in the example given above by checking the file ``xtb.trj``, the water dimer dissociates within 201 | the MTD simulation due to the applied bias potential. If you run dynamics for systems that are non-covalently bound, 202 | you may encounter this problem from time to time. To avoid dissociation you can try to confine the simulation in a sphere by 203 | a repulsive potential. For further details check how to confine a cavity in :ref:`detailed-input`. 204 | 205 | To avoid dissociation of the water dimer by a logfermi potential, the input file has to be modified: 206 | 207 | .. code:: 208 | 209 | > cat metadyn.inp 210 | $md 211 | time=10 212 | step=1 213 | temp=298 214 | $end 215 | $metadyn 216 | atoms: 1-3 217 | save=10 218 | kpush=0.02 219 | alp=1.2 220 | $end 221 | $wall 222 | potential=logfermi 223 | sphere: auto, all 224 | $end 225 | 226 | To start the constrained MTD simulation we call xtb as follows: 227 | 228 | .. code:: bash 229 | 230 | > xtb --md --input metadyn.inp coord 231 | 232 | If you now check the trajectory file, you will see that the water molecules do not separate. 233 | 234 | .. note:: The wall potential does not only work for MD/MTD simulations. 235 | It may also be applied in the same manner for single point calculations and geometry optimizations. 236 | -------------------------------------------------------------------------------- /source/news.rst: -------------------------------------------------------------------------------- 1 | .. _news: 2 | 3 | News 4 | ==== 5 | 6 | % will be replaced by ablog 7 | -------------------------------------------------------------------------------- /source/path.rst: -------------------------------------------------------------------------------- 1 | .. _path: 2 | 3 | ----------------------- 4 | Reaction Path Methods 5 | ----------------------- 6 | 7 | .. important:: 8 | 9 | This guide refers to the meta-dynamics reaction path finder. 10 | While this approach is simpler and usually faster than nugded elastic 11 | band (NEB) methods or growing string methods (GSM) it might not be 12 | as reliable for more difficult reaction paths. 13 | 14 | See the :ref:`gsm` guide for details on alternative reaction path finders. 15 | 16 | .. contents:: 17 | 18 | Setting up the Path Input 19 | ========================= 20 | 21 | The meta-dynamics reaction path finder is based on a simple metadynamics bias 22 | potential adding a repulsive potential on the reactant structure and an 23 | attractive potential on the product structure. 24 | If the potential is chosen correctly a straight-forward geometry optimization 25 | should yield the reaction path between reactant and product. 26 | 27 | The main difficulty lies in the choice of the correct repulsive and attractive 28 | potential to avoid artificial local minima that will stop the optimization. 29 | To overcome this issue the meta-dynamics reaction path finder will run several 30 | combinations of potential shapes to obtain the reaction path. 31 | 32 | A usual invokation of the path finder is given here 33 | 34 | .. code-block:: none 35 | 36 | xtb start.xyz --path end.xyz --input path.inp 37 | 38 | For this guide we will use the GFN2-xTB since we want to form bonds. 39 | 40 | If you want to use GFN-FF, keep in mind, that the GFN-FF can only break bonds, 41 | dissociation reactions will therefore usually work fine, while association 42 | reactions are likely to fail, as the topology is generated for the reactant 43 | geometry. 44 | If you want to model an association try to swap reactant and product and model 45 | the respective dissociation instead or use a quantum mechanical method like 46 | GFN2-xTB instead. 47 | 48 | The recommended settings for running the pathfinder can be somewhat system 49 | dependent, a good starting point is this set of values: 50 | 51 | .. code-block:: none 52 | :caption: path.inp 53 | 54 | $path 55 | nrun=1 56 | npoint=25 57 | anopt=10 58 | kpush=0.003 59 | kpull=-0.015 60 | ppull=0.05 61 | alp=1.2 62 | $end 63 | 64 | 65 | Example Run 66 | ----------- 67 | 68 | A possible input for a Diels-Alder reaction is given here. 69 | The starting structure for this example 70 | 71 | .. code-block:: none 72 | :caption: start.xyz 73 | 74 | 15 75 | 76 | C -1.05403119 -0.85921125 -1.07844148 77 | O -0.74716995 -1.59204846 0.00037929 78 | C 1.91999122 0.31825506 -0.65929558 79 | C -1.56348463 0.34378897 -0.70923752 80 | C -1.05432765 -0.85883374 1.07895685 81 | C 1.92016161 0.31774885 0.65905212 82 | C -1.56373749 0.34366980 0.70888173 83 | H -0.86626022 -1.30691107 -2.03849048 84 | H 2.21980037 -0.54462844 -1.23619995 85 | H 1.61547946 1.18008308 -1.23636699 86 | H -1.89753571 1.13638114 -1.35561033 87 | H -0.86679445 -1.30614725 2.03907198 88 | H 2.21960266 -0.54586684 1.23524723 89 | H 1.61610877 1.17913244 1.23678680 90 | H -1.89780281 1.13623322 1.35526633 91 | 92 | The product structure given here 93 | 94 | .. code-block:: none 95 | :caption: end.xyz 96 | 97 | 15 98 | 99 | C -0.33650300 -0.52567500 -1.05221900 100 | O -0.49920800 -1.44888700 0.00032300 101 | C 1.08232400 0.03657400 -0.76729600 102 | C -1.29917500 0.57935400 -0.66347200 103 | C -0.33671300 -0.52527900 1.05252700 104 | C 1.08262000 0.03575900 0.76715400 105 | C -1.29967800 0.57933100 0.66328300 106 | H -0.47204500 -0.99959700 -2.02194900 107 | H 1.84062900 -0.63339500 -1.16910900 108 | H 1.22478200 1.02637400 -1.19722100 109 | H -1.79017300 1.24152200 -1.35666900 110 | H -0.47213100 -0.99881000 2.02246200 111 | H 1.84129300 -0.63425300 1.16825900 112 | H 1.22479600 1.02528600 1.19777000 113 | H -1.79081700 1.24169700 1.35615700 114 | 115 | Running the calculation should yield an output similar to this 116 | 117 | .. code-block:: none 118 | :emphasize-lines: 35 119 | 120 | ------------------------------------------------- 121 | | P A T H | 122 | | RMSD-Push/Pull Path Finder | 123 | ------------------------------------------------- 124 | reading reference structures from end.xyz ... 125 | reactant product RMSD : 1.010 126 | initial k push/pull (in code xNat) : 0.003 -0.015 127 | initial Gaussian width (1/Bohr) : 1.200 128 | # refinement runs : 1 129 | # of 'an'-optimization steps : 10 130 | # optlevel : 0 131 | 132 | degenerate system : F 0.260023 0.367379 133 | 24 # points, run 1 for k push/pull/alpha : 0.003 -0.015 1.200 prod-ed RMSD: 0.018 134 | 23 # points, run 2 for k push/pull/alpha : 0.003 -0.013 1.200 prod-ed RMSD: 0.017 135 | 136 | path trials (see xtbpath_*.xyz), energies in kcal/mol 137 | run 1 barrier: 116.09 dE: -25.06 product-end path RMSD: 0.018 138 | run 2 barrier: 12.52 dE: -25.08 product-end path RMSD: 0.017 139 | path 2 taken with 23 points. 140 | screening points ... 141 | start path on file xtbpath_0.xyz 142 | refinement cycle 1 143 | optimizing points 2 ... 144 | optimizing points 10 ... 145 | optimizing points 20 ... 146 | 147 | forward barrier (kcal) : 12.420 148 | backward barrier (kcal) : 37.497 149 | reaction energy (kcal) : -25.076 150 | opt. pull strength : 0.050 151 | norm(g) at est. TS, point: 0.01615 11 152 | 153 | terminated because max. # cycles reached 154 | estimated TS on file xtbpath_ts.xyz 155 | path data (pmode=approx. path mode): 156 | point drms energy pmode ovlp pmode grad 157 | 2 0.000 -0.025 0.996 -0.00004 158 | 3 0.066 0.177 0.999 0.00032 159 | 4 0.134 0.570 0.999 0.00062 160 | 5 0.202 1.146 0.999 0.00092 161 | 6 0.269 1.984 0.999 0.00137 162 | 7 0.334 3.094 0.997 0.00179 163 | 8 0.400 4.629 0.995 0.00245 164 | 9 0.466 6.516 0.982 0.00303 165 | 10 0.532 8.988 0.900 0.00373 166 | 11 0.603 12.420 0.939 0.00374 167 | 12 0.700 -12.104 0.772 -0.01147 168 | 13 0.927 -17.963 0.806 -0.01343 169 | 14 0.974 -21.578 0.948 -0.00871 170 | 15 1.018 -23.406 0.612 -0.00549 171 | 16 1.053 -24.364 0.207 -0.00297 172 | 17 1.088 -24.348 -0.080 0.00006 173 | 18 1.117 -24.149 -0.414 0.00084 174 | 19 1.142 -24.574 -0.534 -0.00194 175 | 20 1.165 -24.941 -0.212 -0.00168 176 | 21 1.189 -24.865 -0.748 0.00043 177 | 22 1.208 -25.100 -0.450 -0.00123 178 | 23 1.228 -25.076 0.077 0.00031 179 | 180 | 181 | The final transition state guess can be found in ``xtbpath_ts.xyz``, depicted here: 182 | 183 | .. figure:: ../figures/path-ts.png 184 | :scale: 50 % 185 | :alt: transition state 186 | -------------------------------------------------------------------------------- /source/pcem.rst: -------------------------------------------------------------------------------- 1 | .. _pcem: 2 | 3 | ----------------------------------- 4 | External Potentials and Embedding 5 | ----------------------------------- 6 | 7 | ``xtb`` supports external electrostatic potentials for GFN1-xTB and GFN2-xTB. 8 | 9 | .. contents:: 10 | 11 | Example: The Water Tetramer in Pieces 12 | ===================================== 13 | 14 | As input geometry for the QM half of the water cluster we use 15 | 16 | .. code-block:: none 17 | 18 | $coord 19 | -2.75237178376284 2.43247309226225 -0.01392519847964 O 20 | -0.93157260886974 2.79621404458590 -0.01863384029005 H 21 | -3.43820531288547 3.30583608421060 1.42134539425148 H 22 | -2.43247309226225 -2.75237178376284 0.01392519847964 O 23 | -2.79621404458590 -0.93157260886974 0.01863384029005 H 24 | -3.30583608421060 -3.43820531288547 -1.42134539425148 H 25 | $end 26 | 27 | The setup will look somewhat similar to this 28 | 29 | .. code-block:: bash 30 | 31 | > ls 32 | pcem.input water_4.coord water_4.pc 33 | > cat pcem.input 34 | $embedding 35 | input=water_4.pc 36 | $end 37 | > xtb water_4.coord -I pcem.input 38 | ... 39 | 40 | The file ``water_4.pc`` contains the partial charges and its positions as 41 | 42 | .. code-block:: none 43 | 44 | 6 45 | -0.69645733 2.75237178376284 -2.43247309226225 -0.01392519847964 O 46 | 0.36031084 0.93157260886974 -2.79621404458590 -0.01863384029005 H 47 | 0.33614649 3.43820531288547 -3.30583608421060 1.42134539425148 H 48 | -0.69645733 2.43247309226225 2.75237178376284 0.01392519847964 O 49 | 0.36031084 2.79621404458590 0.93157260886974 0.01863384029005 H 50 | 0.33614649 3.30583608421060 3.43820531288547 -1.42134539425148 H 51 | 52 | The first column contains the partial charge, the second to fourth columns 53 | contain the cartesian coordinates in Bohr (or in Ångström if ``interface=orca`` 54 | is used in the input file). 55 | The fifth column is optional, but can contain, like here, element symbols 56 | to specify the chemical hardnesses of the partial charges. 57 | Note that we are not using real point charges here but a damped Coulomb interaction 58 | consistent to the electrostatic interactions used in the respective 59 | xTB Hamiltonian. 60 | 61 | The read in point charges are shown in the setup block of the SCC as 62 | 63 | .. code-block:: none 64 | :emphasize-lines: 18-20 65 | 66 | ... skip ... 67 | 68 | ------------------------------------------------- 69 | | Self-Consistent Charge Iterations | 70 | ------------------------------------------------- 71 | 72 | ................................................... 73 | : SETUP : 74 | :.................................................: 75 | : # basis functions 12 : 76 | : # atomic orbitals 12 : 77 | : # shells 8 : 78 | : # electrons 16 : 79 | : max. iterations 250 : 80 | : Hamiltonian GFN2-xTB : 81 | : restarted? false : 82 | : GBSA solvation false : 83 | : PC potential true : 84 | : -> # point charges 6 : 85 | : -> sum of PC 0.0000000 e : 86 | : electronic temp. 300.0000000 K : 87 | : accuracy 1.0000000 : 88 | : -> integral cutoff 0.2500000E+02 : 89 | : -> integral neglect 0.1000000E-07 : 90 | : -> SCF convergence 0.1000000E-05 Eh : 91 | : -> wf. convergence 0.1000000E-03 e : 92 | : Broyden damping 0.4000000 : 93 | ................................................... 94 | 95 | iter E dE RMSdq gap omega full diag 96 | 1 -10.2141283 -0.102141E+02 0.418E+00 13.25 0.0 T 97 | 2 -10.2169842 -0.285597E-02 0.241E+00 13.15 1.0 T 98 | 3 -10.2175075 -0.523314E-03 0.392E-01 12.35 1.0 T 99 | 4 -10.2176392 -0.131616E-03 0.871E-02 12.57 1.0 T 100 | 5 -10.2176471 -0.790990E-05 0.417E-02 12.50 1.0 T 101 | 6 -10.2176488 -0.172257E-05 0.237E-03 12.52 17.3 T 102 | 7 -10.2176488 -0.524712E-08 0.835E-04 12.52 48.9 T 103 | 8 -10.2176488 0.134836E-09 0.623E-04 12.52 65.5 T 104 | 105 | *** convergence criteria satisfied after 8 iterations *** 106 | 107 | ... skip ... 108 | 109 | ::::::::::::::::::::::::::::::::::::::::::::::::::::: 110 | :: SUMMARY :: 111 | ::::::::::::::::::::::::::::::::::::::::::::::::::::: 112 | :: total energy -10.155934019173 Eh :: 113 | :: gradient norm 0.024959693967 Eh/a0 :: 114 | :: HOMO-LUMO gap 12.520985724021 eV :: 115 | ::.................................................:: 116 | :: SCC energy -10.217648797540 Eh :: 117 | :: -> isotropic ES 0.066792092832 Eh :: 118 | :: -> anisotropic ES -0.002669047466 Eh :: 119 | :: -> anisotropic XC -0.001310421597 Eh :: 120 | :: -> dispersion -0.000808230531 Eh :: 121 | :: repulsion energy 0.061714760838 Eh :: 122 | :: add. restraining 0.000000000000 Eh :: 123 | ::::::::::::::::::::::::::::::::::::::::::::::::::::: 124 | 125 | ... skip ... 126 | 127 | To obtain point charge like behaviour for the partial charges the chemical 128 | hardness can be set to a large value. This can be done by specifying the chemical 129 | hardnesses in the fifth column instead of giving an element symbol. 130 | For this setup the ``water_4.pc`` would look like 131 | 132 | .. code-block:: none 133 | 134 | 6 135 | -0.69645733 2.75237178376284 -2.43247309226225 -0.01392519847964 99 136 | 0.36031084 0.93157260886974 -2.79621404458590 -0.01863384029005 99 137 | 0.33614649 3.43820531288547 -3.30583608421060 1.42134539425148 99 138 | -0.69645733 2.43247309226225 2.75237178376284 0.01392519847964 99 139 | 0.36031084 2.79621404458590 0.93157260886974 0.01863384029005 99 140 | 0.33614649 3.30583608421060 3.43820531288547 -1.42134539425148 99 141 | -------------------------------------------------------------------------------- /source/periodic_boundary_conditions.rst: -------------------------------------------------------------------------------- 1 | .. _pbc: 2 | 3 | ------------------------------ 4 | Periodic Boundary Conditions 5 | ------------------------------ 6 | 7 | We integrated the xTB methods in `DFTB+`_ to allow reusing the existing code infrastructure for handling periodic boundary condition. 8 | Implementation of the xTB methods is realized via a library spin-off from ``xtb``, which will be upstreamed into this project in the future. 9 | For more details on the integration visit this `page `_. 10 | 11 | .. _DFTB+: http://www.dftbplus.org/ 12 | -------------------------------------------------------------------------------- /source/python.rst: -------------------------------------------------------------------------------- 1 | .. _python: 2 | 3 | ------------------------------------ 4 | Python Integration for the xtb API 5 | ------------------------------------ 6 | 7 | .. warning:: 8 | ``xtb-python`` is no longer in active development. We recommend using `tblite `_ instead. 9 | 10 | The ``xtb`` program does not provide a Python API on its own anymore, 11 | it is now maintained in the ``xtb-python`` project. 12 | 13 | The ``xtb-python`` project is hosted on `GitHub `_. 14 | The documention of the Python API can be found `here `_. 15 | -------------------------------------------------------------------------------- /source/qcxms2_doc/qcxms2.rst: -------------------------------------------------------------------------------- 1 | ----------------------- 2 | Introduction to QCxMS2 3 | ----------------------- 4 | 5 | .. figure:: ../../figures/qcxms2/qcxms2_logo.svg 6 | :align: center 7 | 8 | What is *QCxMS2* ? 9 | ================== 10 | 11 | `QCxMS2` is a quantum chemical (**QC**) based program that enables users to calculate mass spectra (**MS**) 12 | using automated reaction network discovery. The program is designed to simulate the fragmentation of molecules. 13 | It is the successor of the QCxMS program, in which fragmentation reactions are simulated via Born-Oppenheimer Molecular Dynamics (**MD**). 14 | The different MS methods of the program are described in short below. A full list of :ref:`qcxms2relatedrefs` is provided elsewhere. 15 | 16 | The **QCxMS2** program is available and free-of-charge at the QCxMS2 `GitHub page `_ 17 | 18 | 19 | MS methods available 20 | ==================== 21 | 22 | Electron Ionization 23 | ------------------- 24 | 25 | The program was originally developed to calculate Electron Ionization (**EI**) mass spectra, in which a (typically 26 | 70 eV) electron beam is focused on a molecule in order to create an *open-shell* radical ion (uneven number of valence electrons). 27 | This process not only ionizes the molecule, but simultaneously increases the internal energy of the species, which 28 | in turn leads to bond breaking, fragmentation, rearrangement, etc of the ion. A more detailed description can be 29 | found in the `original publication`_. 30 | 31 | .. _original publication: https://doi.org/10.26434/chemrxiv-2025-277zm 32 | 33 | 34 | Dissociative Electron Attachment 35 | -------------------------------- 36 | 37 | In contrast to the positive ions created by the EI process, the Dissociative Electron Attachment (**DEA**) ionizes the 38 | molecule under study by adding an electron. This creates a negatively charged ion (*open-shell* ion). 39 | 40 | .. note:: 41 | The DEA mode is not yet tested for QCxMS2 but works technically. It should therefore be used with caution. 42 | The negative ions have to be described by using DFT and diffuse basis functions which increases the computational costs 43 | significantely. 44 | 45 | Collision Induced Dissociation 46 | ------------------------------ 47 | 48 | Ionization of molecules can be done by (de)protonation, *e.g.*, by the popular electrospray ionization (ESI) method. 49 | This ionization process produces *closed-shell* ions (even number of valence electrons) and is softer than the EI or DEA methods. 50 | It is often implemented by (de-)protonation of the molecule under study, leading to positivly or negativly charged 51 | molecular ions. The following Collision Induced Dissociation (**CID**) leads to a spectrum normally under lower energy conditions than in 52 | the other MS methods. 53 | 54 | .. note:: 55 | A special CID mode is not yet implemented for QCxMS2. However, the EI mode can be used to simulate CID spectra. 56 | However, special settings for the energy distribution (probably lower than the default settings for EI-MS) 57 | should be tested to reproduce experimental spectra. 58 | Investigations on the ability of QCxMS2 to simulate CID spectra are ongoing. For now, we recommend to use the 59 | predecessor QCxMS :ref:`qcxms` for CID simulations. -------------------------------------------------------------------------------- /source/qcxms2_doc/qcxms2_cites.rst: -------------------------------------------------------------------------------- 1 | 2 | .. _qcxms2relatedrefs: 3 | 4 | ------------------------------------- 5 | QCxMS2 related publications 6 | ------------------------------------- 7 | 8 | Electron Ionizaion 9 | ================== 10 | 11 | J. Gorges, S. Grimme *QCxMS2 - a program for the calculation of electron ionization mass spectra via automated reaction network discovery .* 12 | *ChemRxiv*, **2025**. 13 | `DOI: 10.26434/chemrxiv-2025-277zm `_ 14 | 15 | 16 | -------------------------------------------------------------------------------- /source/qcxms2_doc/qcxms2_plot.rst: -------------------------------------------------------------------------------- 1 | .. _qcxms2_plot: 2 | 3 | -------------- 4 | Visualization 5 | -------------- 6 | 7 | 8 | QCxMS2 prints the computed spectrum in the ``peaks.csv`` file with the following specifications: 9 | 10 | +--------------------+----------------------------+--------------------+ 11 | | m/z ** | , | intensity ** | 12 | +--------------------+----------------------------+--------------------+ 13 | | m/z ** | , | intensity ** | 14 | +--------------------+----------------------------+--------------------+ 15 | | `.....` | , | `.....` | 16 | +--------------------+----------------------------+--------------------+ 17 | 18 | The ``peaks.csv`` file can be visualized using any suitable plotting tools. 19 | 20 | 21 | .. note:: 22 | A python plotting package is currently under development to ease the visualization of the spectrum including 23 | the fragmentation pathways leading to specific spectral peaks. 24 | 25 | 26 | Program flags and command-line options 27 | --------------------------------------- 28 | 29 | You can generate the 'peaks.csv' of a finished QCxMS2 calculation with the following command: 30 | 31 | .. code:: 32 | 33 | qcxms2 [INPUT] -- oplot [OPTIONS] 34 | 35 | 36 | There are some useful options for manipulating the output of the spectrum: 37 | 38 | 39 | .. list-table:: Options for generating the mass spectrum: 40 | :widths: 30 100 41 | :header-rows: 1 42 | 43 | * - ``-noisotope`` 44 | - only plot peak with the highest isotope probability 45 | * - ``-int_masses`` 46 | - only plot masses as integers 47 | * - ``-mthr [real]`` 48 | - m/z at which spectral peaks plotted (default 0) 49 | * - ``-intthr [real]`` 50 | - peak intensity threshold at which spectral peaks are plotted in percent (default 0) 51 | 52 | 53 | 54 | 55 | 56 | Investigation of fragmentation pathways 57 | ============================= 58 | 59 | 60 | A QCxMS2 calculation contains also information the fragmentation pathways leading to a specific peak in the mass spectrum. 61 | 62 | QCxMS2 prints the computed spectrum in the ``peaks.csv`` file with the following specifications: 63 | 64 | 65 | +--------------------+---------------------+-----------------------------+ 66 | | input structure | m/z ** | relative intensity ** | 67 | +--------------------+---------------------+-----------------------------+ 68 | | fragment directory | m/z ** | relative intensity ** | 69 | +--------------------+---------------------+-----------------------------+ 70 | | | | | 71 | +--------------------+---------------------+-----------------------------+ 72 | 73 | The first column gives the location of the xyz coordingate file of the respective species. 74 | The product of a fragmentation reaction can be found in the pXX directories. 75 | For isomer products, the ``isomer.xyz`` file can be found directly in this directory. For fragmentation products, 76 | the ``pair.xyz`` file can be found in the respective pair directory pXX and the ``fragment.xyz`` files in the respective 77 | fragment directories pXXf1 and pXXf2. 78 | 79 | The second column gives the m/z value of the respective species. It is the exact mass of the isotope combination with the highest probability 80 | for the specific atom composition. 81 | 82 | The third column contains the relative intensity normalized to 10000 arbitrary units. 83 | 84 | For subsequent fragmentations, the directory name is contains the complete reaction path to end up at the specific fragment. 85 | For example, the p1XXfX directories contain all products of the first isomerization product in the first fragmentation step. 86 | Likewise, the the p10f1pXXfX directories contain all products of fragment 1 of the 10th fragmentation product in the first fragmentation step. 87 | 88 | Additional information about reaction energies and barriers of the reaction network can be found in the ``allframgents`` file. 89 | The file contains the following information: 90 | 91 | +-----+---------------+--------------------+---------------+--------------------+------------+ 92 | + Dir | fragment_type | sumreac (kcal/mol) | de (kcal/mol) | barrier (kcal/mol) | irc (cm-1) | 93 | +-----+---------------+--------------------+---------------+--------------------+------------+ 94 | 95 | For each species, the following information is given: 96 | 97 | Dir: Directory of the species in the nomenclature described above. 98 | 99 | fragment_type: isomer, fragmentpair 100 | 101 | sumreac: Sum of the reaction energies of the reaction network leading to the specific species including the zero-point vibrational energy (ZPVE). 102 | 103 | de: Reaction energy of the specific reaction leading to the specific species including the zero-point vibrational energy (ZPVE). 104 | 105 | barrier: Reaction barrier of the specific reaction leading to the specific species including the zero-point vibrational energy (ZPVE). 106 | 107 | irc: Imaginary frequency of the transition state of the respective reaction. If no irc could be identified, 0 is printed here. 108 | 109 | The next line contains information about the product directory, the molecular mass, the sum formula and the relative intensity in percent of the species. 110 | 111 | 112 | 113 | 114 | 115 | 116 | -------------------------------------------------------------------------------- /source/qcxms2_doc/qcxms2_run.rst: -------------------------------------------------------------------------------- 1 | .. _qcxms2_run: 2 | 3 | -------------------- 4 | Settings for QCxMS2 5 | -------------------- 6 | 7 | Settings of a QCxMS2 run can be changed via the following command line options: 8 | 9 | .. code:: 10 | 11 | qcxms2 [INPUT] [OPTIONS] 12 | 13 | .. list-table:: General Settings 14 | :widths: 30 100 15 | :header-rows: 1 16 | 17 | * - Command 18 | - Description 19 | * - ``-h, --help`` 20 | - Print an overview of most available options (i.e., more or less this site completely). 21 | * - **Runtype Options**: 22 | - 23 | * - ``-ei`` 24 | - Compute an electron impact (EI) spectrum (default). 25 | * - ``-esim`` 26 | - Simulate only different IEE distributions for a given reaction network from a previous calculation. 27 | * - ``-oplot`` 28 | - Plot only peaks from the previous QCxMS2 calculation. 29 | * - **General and Technical Options**: 30 | - 31 | * - ``-chrg [int]`` 32 | - Give charge of the input molecule. 33 | * - ``-edist`` 34 | - Choose distribution for IEE ("poisson" (default) or "gaussian"). 35 | * - ``-eimp0`` 36 | - Specify impact energy of electrons in eV (default: 70). 37 | * - ``-eimpw`` 38 | - Specify width of energy distribution (default: 0.1). 39 | * - ``-ieeatm`` 40 | - Specify energy per atom in eV (default: 0.8). 41 | * - ``-nots`` 42 | - Take reaction energy instead of barrier → no path search (quick mode for fragments). 43 | * - ``-T`` 44 | - Select the number of overall cores (default: 4). 45 | * - ``-nfrag [integer]`` 46 | - Select the number of subsequent fragmentations you want to simulate (default: 6). 47 | * - ``-pthr [real]`` 48 | - Specify the intensity at which a fragment is further fragmented in % (default: 1%). 49 | 50 | .. list-table:: Quantum Chemical calculation settings 51 | :widths: 30 100 52 | :header-rows: 1 53 | 54 | * - **Options for QC Calculations**: 55 | - 56 | * - ``-nebnormal`` 57 | - Use normal settings instead of loose settings for NEB search. 58 | * - ``-notsgeo`` 59 | - Do not use geodesic interpolation as a guess for restarting non-converged NEB runs. 60 | * - ``-tsnodes [integer]`` 61 | - Select the number of nodes for the path (default: 9). 62 | * - ``-geolevel [method]`` 63 | - Method for geometry optimization and path search. 64 | * - ``-tslevel [method]`` 65 | - Select level for computing reaction barriers. 66 | * - ``-iplevel [method]`` 67 | - Select level for computing IPs for charge assignment. 68 | * - ``-ip2level [method]`` 69 | - Select level for computing IPs for charge assignment of critical cases with close IPs (difference below 2 eV). 70 | 71 | The default for all levels is GFN2-xTB. 72 | The following methods are available for all four different levels: 73 | 74 | +-------------+----------------------+-------------+ 75 | | **Keyword** | **QM Method** | **Program** | 76 | +-------------+----------------------+-------------+ 77 | | gfn2 | GFN2-xTB | xtb | 78 | +-------------+----------------------+-------------+ 79 | | gfn1 | GFN1-xTB | xtb | 80 | +-------------+----------------------+-------------+ 81 | | r2scan3c | r2SCAN-3c | ORCA | 82 | +-------------+----------------------+-------------+ 83 | | pbeh3c | PBEh-3c | ORCA | 84 | +-------------+----------------------+-------------+ 85 | | wb97x3c | wB97X-3c | ORCA | 86 | +-------------+----------------------+-------------+ 87 | | pbe0 | PBE0-D4/def2-TZVP | ORCA | 88 | +-------------+----------------------+-------------+ 89 | | pbe0matzvp | PBE0-D4/ma-def2-TZVP | ORCA | 90 | +-------------+----------------------+-------------+ 91 | 92 | .. note:: 93 | The recommended settings are GFN2-xTB for geometry optimizations (``-geolevel``) and IP prescreening (``-iplevel``) 94 | and the efficient range-seperated hybrid wB97X-3c for barrier and energy calculations and refinement of 95 | close IPs (``-tslevel`` and ``-ip2level``). Using DFT for the geometry optimization 96 | is very expensive and only recommend for very small systems. For the prescreening of IPs, GFN2-xTB is 97 | more moste cases sufficient. However, for difficult systems, e.g., negative ions, DFT should be used. 98 | The hybrid functional PBE0-D4 with mininimal augmented basis set (``pbe0matzvp``) is recommended here both for 99 | ``-iplevel`` and ``-ip2level``. 100 | 101 | 102 | .. list-table:: Further Settings 103 | :widths: 30 100 104 | :header-rows: 1 105 | 106 | * - **Options for Fragment Generation with CREST msreact**: 107 | - 108 | * - ``-msnoiso`` 109 | - Sort out non-dissociated fragments in CREST msreact (i.e., rearranged structures). 110 | * - ``-msiso`` 111 | - Sort out dissociated fragments in CREST msreact (i.e., rearranged structures). 112 | * - ``-msfulliso`` 113 | - Allow rearrangements for subsequent fragmentations in CREST msreact (activated by default). 114 | * - ``-msnoattrh`` 115 | - Deactivate the attractive potential between hydrogen and LMO centers. 116 | * - ``-msnshifts [int]`` 117 | - Perform `n` optimizations with randomly shifted atom positions (default: 0). 118 | * - ``-msnshifts2 [int]`` 119 | - Perform `n` optimizations with randomly shifted atom positions and a repulsive potential applied to bonds (default: 0). 120 | * - ``-msnbonds [int]`` 121 | - Maximum number of bonds between atom pairs for applying a repulsive potential (default: 3). 122 | * - ``-msmolbar`` 123 | - Sort out topological duplicates by molbar codes (activated by default—requires "molbar"). 124 | * - ``-msinchi`` 125 | - Sort out topological duplicates by InChI codes (requires "obabel"). 126 | * - ``-msnfrag [int]`` 127 | - Number of fragments printed by msreact (random selection). 128 | * - ``-msfragdist [real]`` 129 | - Separate fragments before TS search from each other (default: 2.5 Å). 130 | * - **Special Options**: 131 | - 132 | * - ``-noKER`` 133 | - Do not compute kinetic energy release (KER). 134 | * - ``-usetemp`` 135 | - Use G_mRRHO contributions instead of only ZPVE (ZPVE is default). 136 | * - ``-scaleeinthdiss [real]`` 137 | - Decrease the internal energy only for -H or -H2 abstractions (default: 0.5). 138 | * - ``-nsamples [int]`` 139 | - Number of simulated runs in Monte Carlo (default: 10E05). 140 | * - ``-rrkm`` 141 | - Compute rate constants via the RRKM equation instead of Eyring (default: Eyring). 142 | * - ``-sthr [int]`` 143 | - RRHO cutoff for thermo contributions (default: 150 cm⁻¹). 144 | * - ``-ithr [int]`` 145 | - Imaginary RRHO cutoff for thermo contributions (default: 100 cm⁻¹). 146 | * - ``-nthermosteps [int]`` 147 | - Number of increments to compute thermal corrections for the IEE distribution (default: 200; take a multiple of 10). 148 | 149 | 150 | 151 | 152 | -------------------------------------------------------------------------------- /source/qcxms2_doc/qcxms2_setup.rst: -------------------------------------------------------------------------------- 1 | ***************** 2 | Setting up QCxMS2 3 | ***************** 4 | 5 | .. contents:: Table of Contents 6 | 7 | Pre-compiled binaries from GitHub 8 | ================================= 9 | 10 | A pre-compiled executable of the latest program version can be found on the `latest release 11 | `_ page on GitHub. 12 | Follow the instructions to use QCxMS2 without the need of building anything. 13 | 14 | Untar the zipped archive: 15 | 16 | .. code-block:: text 17 | 18 | > tar -xvzf QCxMS2.v.X.X.tar.xz 19 | 20 | Replace the *X.X* with the current version number. 21 | The program is designed to run on Linux operating systems. 22 | 23 | The following files are being extracted: 24 | 25 | +-----------------+----------------------------------------------------------------------------------------------+ 26 | | qcxms2 | main program (`executable`) | 27 | +-----------------+----------------------------------------------------------------------------------------------+ 28 | 29 | 30 | 1. Place the `executable` into your ``$HOME/bin`` directory or path. 31 | 32 | 33 | 34 | Quantum Chemistry Codes Required 35 | ================================ 36 | 37 | QCxMS2 needs several external codes. 38 | 39 | They have to be installed on your system, 40 | either by using ``environment modules`` or by placing the executables in your ``$HOME/bin`` directory or path 41 | with **exactly** the name as stated in the following Table. 42 | You should check that each of these programs works on your system before running QCxMS2. 43 | The QCxMS2 program will only check for the presence of these programs at the beginning of the calculation. 44 | 45 | 46 | +----------------------------------+----------------------------+----------------------------------------------------------------------+ 47 | | required name of the executable | required version | link to the software repository | 48 | +----------------------------------+----------------------------+----------------------------------------------------------------------+ 49 | | xtb | > 6.7.1 (bleeding edge) | `xtb `_ | 50 | +----------------------------------+----------------------------+----------------------------------------------------------------------+ 51 | | crest | >= 3.0.2 | `crest `_ | 52 | +----------------------------------+----------------------------+----------------------------------------------------------------------+ 53 | | orca | >= 6.0.0 | `orca `_ | 54 | +----------------------------------+----------------------------+----------------------------------------------------------------------+ 55 | | molbar | >= 1.1.3 | `molbar `_ | 56 | +----------------------------------+----------------------------+----------------------------------------------------------------------+ 57 | | geodesic_interpolate (optional) | >= 1.0.0 | `geodesic `_ | 58 | +----------------------------------+----------------------------+----------------------------------------------------------------------+ 59 | 60 | Please cite the respective publications when using the software in your research. 61 | 62 | -------------------------------------------------------------------------------- /source/qcxms_doc/qcxms.rst: -------------------------------------------------------------------------------- 1 | .. _qcxms: 2 | 3 | ----------------------- 4 | Introduction to QCxMS 5 | ----------------------- 6 | 7 | .. figure:: ../../figures/qcxms/qcxms_logo.svg 8 | :align: center 9 | 10 | What is *QCxMS* ? 11 | ================== 12 | 13 | `QCxMS` is a quantum chemical (**QC**) based program that enables users to calculate mass spectra (**MS**) 14 | using Born-Oppenheimer Molecular Dynamics (**MD**). 15 | It is the successor of the QCEIMS program, in which the **EI** part is exchanged to **x** (x=EI, CID) to account 16 | for the greater general applicability of the program. The different MS methods of the program are described in short 17 | below. A full list of :ref:`qcxmsrelatedrefs` is provided elsewhere. 18 | 19 | The **QCxMS** program is available and free-of-charge at the QCxMS `GitHub page `_ 20 | 21 | MS methods available 22 | ==================== 23 | 24 | Electron Ionization 25 | ------------------- 26 | 27 | The program was originally developed to calculate Electron Ionization (**EI**) mass spectra, in which a (typically 28 | 70 eV) electron beam is focused on a molecule in order to create an *open-shell* radical ion (uneven number of valence electrons). 29 | This process not only ionizes the molecule, but simultaneously increases the internal energy of the species, which 30 | in turn leads to bond breaking, fragmentation, rearrangement, etc of the ion. A more detailed description can be 31 | found in the `original publication`_. 32 | 33 | .. _original publication: https://doi.org/10.1002/anie.201300158 34 | 35 | 36 | Dissociative Electron Attachment 37 | -------------------------------- 38 | 39 | In contrast to the positive ions created by the EI process, the Dissociative Electron Attachment (**DEA**) ionizes the 40 | molecule under study by adding an electron. This creates a negatively charged ion (*open-shell* ion), which has to be described by 41 | diffuse basis functions. This increases the computational cost because DFT has to be used to compute the PES. 42 | Details on this MS method are described in `this publication`_. 43 | 44 | .. _this publication: http://dx.doi.org/10.1039/C6CP06180J 45 | 46 | Collision Induced Dissociation 47 | ------------------------------ 48 | 49 | Ionization of molecules can be done by (de)protonation, *e.g.*, by the popular electrospray ionization (ESI) method. 50 | This ionization process produces *closed-shell* ions (even number of valence electrons) and is softer than the EI or DEA methods. 51 | It is often implemented by (de-)protonation of the molecule under study, leading to positivly or negativly charged 52 | molecular ions. 53 | Activation of the ion has to be conducted in a second step, *i.e.*, by acceleration and subsequent collisions with neutral collision gas atoms. 54 | The following Collision Induced Dissociation (**CID**) leads to a spectrum normally under lower energy conditions than in 55 | the other MS methods. 56 | The simulation conditions and specific details are extensively covered in `this paper`_. 57 | 58 | .. _this paper: https://doi.org/10.1021/jasms.1c00098 59 | 60 | -------------------------------------------------------------------------------- /source/qcxms_doc/qcxms_cites.rst: -------------------------------------------------------------------------------- 1 | 2 | .. _qcxmsrelatedrefs: 3 | 4 | ------------------------------------- 5 | QCxMS and QCEIMS related publications 6 | ------------------------------------- 7 | 8 | Electron Ionizaion 9 | ================== 10 | 11 | S. Grimme *Towards First Principles Calculation of Electron Impact Mass Spectra of Molecules.* 12 | *Angew. Chem. Int. Ed.*, **2013**, 52, 6306-631. 13 | `DOI: 10.1002/anie.201300158 `_ 14 | 15 | Bauer, C. A.; Grimme, S. *First principles calculation of electron ionization mass spectra for selected organic drug molecules.* *Org. Biomol. Chem.*, **2014**, 12, 8737-8744. 16 | `DOI: 10.1039/C4OB01668H `_ 17 | 18 | Bauer, C. A.; Grimme, S. *Elucidation of Electron Ionization Induced Fragmentations of Adenine by Semiempirical and Density Functional Molecular Dynamics.* 19 | *J. Phys. Chem. A*, **2014**, 118, 11479-11484. 20 | `DOI: 10.1021/jp5096618 `_ 21 | 22 | Bauer, C. A.; Grimme, S. *Automated Quantum Chemistry Based Molecular Dynamics Simulations of Electron Ionization Induced Fragmentations of the Nucleobases Uracil, Thymine, Cytosine, and Guanine.* 23 | *Eur. J. Mass Spectrom.*, **2015**, 21, 125−140. 24 | `DOI: 10.1255/ejms.1313 `_ 25 | 26 | Bauer, C. A.; Grimme, S. *How to Compute Electron Ionization Mass Spectra from First Principles.* 27 | *J. Phys. Chem. A*, **2016**, 120, 3755-3766. 28 | `DOI: 10.1021/acs.jpca.6b02907 `_ 29 | 30 | xTB implementation: 31 | ------------------- 32 | 33 | Asgeirsson, V.; Bauer, C. A.; Grimme, S. *Quantum chemical calculation of electron ionization mass spectra for general organic and inorganic molecules.* 34 | *Chem. Sci.*, **2017**, 8, 4879−4895. 35 | `DOI: 10.1039/C7SC00601B `_ 36 | 37 | Koopman, J.; Grimme, S. *Calculation of Electron Ionization Mass Spectra with Semiempirical GFNn-xTB Methods.* 38 | *ACS Omega*, **2019**, 4, 15120−15133. 39 | `DOI: 10.1021/acsomega.9b02011 `_ 40 | 41 | 42 | Dissociative Electron Attachment 43 | ================================ 44 | 45 | Asgeirsson, V.; Bauer, C.A.; Grimme, S. *Unimolecular decomposition pathways of negatively charged nitriles by ab initio molecular dynamics.* 46 | *Phys. Chem. Chem. Phys.*, **2016**, 18, 31017-31026. 47 | `DOI: 10.1039/C6CP06180J `_ 48 | 49 | Collision Induced Dissociation 50 | ============================== 51 | 52 | Koopman, J.; Grimme, S. *From QCEIMS to QCxMS: A Tool to Routinely Calculate CID Mass Spectra Using Molecular Dynamics.* 53 | *J. Am. Soc. Mass Spectrom*, **2021**. 54 | `DOI: 10.1021/jasms.1c00098 `_ 55 | 56 | Schreckenbach, S.A; Anderson, J.S.M; Koopman, J.; Jobst, K. *Predicting the Mass Spectra of Environmental Pollutants 57 | Using Computational Chemistry: A Case Study and Critical Evaluation.* 58 | *J. Am. Soc. Mass Spectrom*, **2021**. 59 | `DOI: 10.1021/jasms.1c00078 `_ 60 | 61 | Schnegotzki, R.; Koopman, J., Grimme, S.; Süssmuth, R.D. *Quantum Chemistry‐based Molecular Dynamics Simulations as a 62 | Tool for the Assignment of ESI‐MS/MS Spectra of Drug Molecules.* 63 | *Eur. J. Chem.*, **2022** 64 | `DOI: 10.1002/chem.202200318 `_ 65 | 66 | Koopman, J.; Grimme, S. *Calculation of mass spectra with the QCxMS method for negatively and multiply charged 67 | molecules.* 68 | *ChemRxiv*, **2022** 69 | `DOI: 10.26434/chemrxiv-2022-w5260 `_ 70 | 71 | 72 | -------------------------------------------------------------------------------- /source/qcxms_doc/qcxms_ex.rst: -------------------------------------------------------------------------------- 1 | .. _qcxms_example: 2 | 3 | ---------- 4 | Quickstart 5 | ---------- 6 | 7 | The default settings provided in QCxMS are a good starting point for the calculations. 8 | The default setting is performing an `EI`_ calculation. 9 | 10 | To change the behavior of the program, keywords have to be put into a *qcxms.in* file. 11 | The file can be created manually, or is created automatically by first running the program, using the *default* 12 | settings. 13 | If other run modes are required (*e.g.* CID or DEA), example inputs are given below. 14 | The keywords provided are points of orientation and there are more settings that can be used to tune the calculations which 15 | are described in detail in section :ref:`run_qcxms`. 16 | 17 | .. note:: 18 | The default values are **not always** giving the best results, but are set to cover the majority of systems. 19 | Molecules have different characteristics that can significantely influence the outcome. 20 | Changing the input settings can improve upon the final result, e.g. decreasing the molecular ion peak abundance or 21 | producing more low *m/z* fragments. 22 | 23 | EI - positive Ion Electron Ionization 24 | ------------------------------------- 25 | .. _EI: 26 | 27 | .. code:: 28 | 29 | ei 30 | xtb2 31 | ntraj ** 32 | tmax ** 33 | eimp0 ** 34 | 35 | The EI run mode is automatically used with the [*default*] settings described by the keywords, leading to a run using 36 | ``xtb2``, so actually there is no keyword required in the *qcxms.in* file. 37 | To provide some guidance, the setting showed above can be used and the ** and ** placeholders switched to 38 | actual values. 39 | 40 | DEA - negative Ion Electron Ionization 41 | -------------------------------------- 42 | 43 | .. code:: 44 | 45 | ei 46 | 47 | 48 | charge -1 49 | upper 15 50 | lower 0 51 | 52 | For EA calculations, the ma-def2-SVP/ma-def2-TZVP basis sets are recommended. 53 | Production runs are recommended to be conducted at DFT level, however, these are computationally very expensive and GFN-xTB can be 54 | used for a quantitative overview. 55 | The most cost-effordable DFT settings are ** = ``PBE`` | ** = ``ma-def2-svp`` 56 | 57 | Less IEE energy is required for DEA fragmentation, so it is recommended to reduce the IEE distribution limits 58 | by using the ``upper`` and ``lower`` keywords (the old keywords ``dea`` and ``scan`` are obsolete). 59 | 60 | 61 | CID - positive Ion Collision Induced Dissociation 62 | ------------------------------------------------- 63 | 64 | .. code:: 65 | 66 | cid 67 | xtb2 68 | charge 1 69 | elab 40 70 | lchamb 0.25 71 | 72 | The *general activation method* is automatically used, but can also be expicitely switched on using the ``fullauto`` keyword. 73 | 74 | For the *forced activation run-type*, use ``collauto``. 75 | The number of collisions are set by using ``collno`` ** to set number of collisions (including fragment-gas 76 | collisions (*fgc*)). 77 | For setting ONLY ion--gas collisions, use ``maxcoll`` **. 78 | 79 | The *thermal activation method* is switched on with ``temprun`` and scales the internal energy to a value given by the 80 | keyword ``esi`` **. 81 | This is the fastest method, but requires a good initial guess for the internal energy value. 82 | 83 | For more details, see section :ref:`run_qcxms`. 84 | 85 | -------------------------------------------------------------------------------- /source/qcxms_doc/qcxms_plot.rst: -------------------------------------------------------------------------------- 1 | .. _plotms: 2 | 3 | -------------- 4 | Visualization 5 | -------------- 6 | 7 | Plotting Mass Spectra (PlotMS) 8 | ============================== 9 | 10 | 11 | The **PlotMS** utility was developed to visualize the results of `QCxMS `_ 12 | calculations. The newest version can be found in the `PlotMS repository `_. 13 | 14 | The program analyzes the *qcxms.res* or *qcxms_cid.res* file and provides the results as *m/z*-values and abundances. 15 | Versions 6.0 and higher provide **exact masses** of the fragments. 16 | 17 | To run the program, extract the PlotMS executable 18 | 19 | .. code-block:: text 20 | 21 | > tar -xvzf PlotMS.v.X.X.tar.xz 22 | 23 | Replace the *X.X* with the current version number. 24 | The program is designed to run on Linux operating systems. 25 | 26 | Move the ``.mass_raw.agr`` file into the ``$HOME`` folder. Change into your working directory, in which you created the 27 | *qcxms.res* or *qcxms_cid.res* file and run ``plotms``. This generates three files: 28 | 29 | - `mass.agr` -> *XMGRACE* file using the `~/.mass_raw.agr` template file 30 | - `results.jdx` -> *JCAMP-DX* ( *Joint Committee on Atomic and Molecular Physical* data) file 31 | - `results.csv` -> *CSV* (*comma seperated values*) file for spreadsheet programs (e.g. Excel) 32 | 33 | The spectra can be plotted as soon as the production run has started by using the `getres` script, which creates an 34 | *tmpqcxms.res* file. The file has to be deleted before ``getres`` is used a second time. 35 | 36 | For comparison to experiment, a file including the intensity and *m/z* values can be copied into 37 | the folder of the *.res* file. 38 | The file can be read in using `plotms -i `. 39 | Most recommended is using a *.csv* file format with the following specifications: 40 | 41 | +--------------------+----------------------------+--------------------+ 42 | | m/z ** | , | intensity ** | 43 | +--------------------+----------------------------+--------------------+ 44 | | m/z ** | , | intensity ** | 45 | +--------------------+----------------------------+--------------------+ 46 | | `.....` | , | `.....` | 47 | +--------------------+----------------------------+--------------------+ 48 | 49 | PlotMS will than plot the *.agr* file with direct comparison between computed and experimental 50 | results. 51 | A dot matching score is printed at the end of the program output. 52 | 53 | For a comparison to experimental integer spectra from the 54 | `NIST database `_ (*JCAMP-DX* format), the file can be copied 55 | into the working directory as `nist.dat`. 56 | 57 | 58 | Program flags and command-line options 59 | --------------------------------------- 60 | 61 | There are some useful command-line options to manipulate your results. 62 | 63 | -v, --verbose 64 | print verbose options 65 | 66 | -f, --file 67 | provide `.res` file for plotting the spectrum 68 | 69 | -t 70 | couting ions with charge *x* to *y* (give the value, e.g. "-t 1 2" for charge 1 to 2) 71 | 72 | -w, --width 73 | broadening the charges by an standard distribution (given in decimal numbers between 0 and 1) 74 | 75 | -s, --cascades 76 | account only for only secondary and tertiary fragmentations (give the value, e.g. "-s 2" for secondary) 77 | 78 | -m, --min 79 | set minimum value for m/z, so rel. 100% value will be calculated for higher masses (x-axis) 80 | 81 | -i, --mzmin 82 | set the minimum rel. intensity from which the signals are counted (y-axis) 83 | 84 | -p, --noisotope 85 | do not calculate the isotope pattern 86 | 87 | -e, --exp 88 | use the following file as input for comparison to the calculated spectrum 89 | 90 | 91 | Visualization of Trajectories 92 | ============================= 93 | 94 | Trajectories are saved in the *TMPQCXMS/TMP.XXX* directories, where NUM is the first number of the specific 95 | trajectory track to be visualized. There are two programs that can easily display the trajectories, which 96 | are saved in the *trj.NUM.xxx* files. One is `(g)molden`, the other is `VMD`. Obtaining a video (.avi) of a 97 | given trajectory is possibly most easily done by loading the trajectory of choice into VMD (file type .xyz). 98 | 99 | The `msmovie` and `movie.tcl` scripts for `VMD` generate a visualization using the dynamic bonds graphical representations 100 | setting. This allows for movie generation employing the `VMD` movie maker plug-in. Simply type msmovie X Y in the 101 | working directory to load the trajectory *TMPQCXMS/TMP.X/trj.X.Y*. For instance, `msmovie 1 1` loads the first 102 | trajectory of the first folder. 103 | Some adjustments according to personal preferences for movie-making may have to be made in these scripts. 104 | 105 | -------------------------------------------------------------------------------- /source/qcxms_doc/qcxms_setup.rst: -------------------------------------------------------------------------------- 1 | ***************** 2 | Setting up QCxMS 3 | ***************** 4 | 5 | .. contents:: Table of Contents 6 | 7 | Pre-compiled binaries from GitHub 8 | ================================= 9 | 10 | A pre-compiled executable of the latest program version can be found on the `latest release 11 | `_ page on GitHub. 12 | Follow the instructions to use QCxMS without the need of installing or building anything. 13 | 14 | Untar the zipped archive: 15 | 16 | .. code-block:: text 17 | 18 | > tar -xvzf QCxMS.v.X.X.tar.xz 19 | 20 | Replace the *X.X* with the current version number. 21 | The program is designed to run on Linux operating systems. 22 | 23 | The following files are being extracted: 24 | 25 | +-----------------+----------------------------------------------------------------------------------------------+ 26 | | qcxms | main program (`executable`) | 27 | +-----------------+----------------------------------------------------------------------------------------------+ 28 | | pqcxms | script that runs trajectories in parallel locally (`executable`) | 29 | +-----------------+----------------------------------------------------------------------------------------------+ 30 | | q-batch | script that runs trajectories on a cluster with a queueing system (`executable`) | 31 | +-----------------+----------------------------------------------------------------------------------------------+ 32 | | getres | script that gives the status of the parallel QCxMS production run (`executable`) | 33 | +-----------------+----------------------------------------------------------------------------------------------+ 34 | | `.XTBPARAM` | folder involving the xTB-parameterfiles .param_gfn.xtb, .param_gfn2.xtb and .param_ipea.xtb | 35 | +-----------------+----------------------------------------------------------------------------------------------+ 36 | | EXAMPLE | folder hosting an example input and coordinate file. | 37 | +-----------------+----------------------------------------------------------------------------------------------+ 38 | 39 | 40 | 1. Place the `executables` into your ``$HOME/bin`` directory or path. 41 | 2. Place the `.XTBPARAM` folder into your ``$HOME`` directory (these files can appear to be hidden). 42 | 43 | 44 | For easy visualization of the calculated spectra, the **PlotMS** program was developed. 45 | An instruction can be found in section :ref:`plotms` and the program can be downloaded at the 46 | `PlotMS repository `_. 47 | To display the results, we recommend the useage of ``xmgrace``. 48 | Exemplary input and coordinate files can be found in the `EXAMPLES` folder. 49 | 50 | 51 | Installing with Conda 52 | ===================== 53 | 54 | .. note:: 55 | 56 | To bootstrap a conda installation we recommend to either use 57 | the conda-forge distribution 58 | `miniforge `_ 59 | or the anaconda distribution 60 | `miniconda `_. 61 | 62 | Installing ``qcxms`` from the conda-forge channel can be achieved by adding conda-forge to your channels with: 63 | 64 | .. code-block:: none 65 | 66 | conda config --add channels conda-forge 67 | 68 | Once the conda-forge channel has been enabled, ``qcxms`` can be installed with: 69 | 70 | .. code-block:: none 71 | 72 | conda install qcxms 73 | 74 | It is possible to list all of the versions of ``qcxms`` available on your platform with: 75 | 76 | .. code-block:: none 77 | 78 | conda search qcxms --channel conda-forge 79 | 80 | .. note:: 81 | 82 | The conda package manager can become quite slow when adding large channels 83 | like conda-forge, for a more performant alternative you can try to use 84 | `mamba `_ instead, which can be conveniently 85 | installed from the conda-forge channel with 86 | 87 | .. code-block:: none 88 | 89 | conda install mamba -c conda-forge 90 | 91 | Alternatively, the `mambaforge `_ 92 | installed can be used to bootstrap a conda installation with mamba preinstalled. 93 | 94 | 95 | 96 | Quantum Chemistry Codes Required 97 | ================================ 98 | 99 | The low cost QC methods **GFN1-xTB** and **GFN2-xTB** are directly implemented into QCxMS `via` the `tblite framework `_. 100 | With this, no further installations of third-party software is required to create a spectrum at the semi-empirical level of theory. 101 | GFN2-xTB is set to run as default for QCxMS calculations. 102 | 103 | To run other QC methods (e.g. DFT), ORCA or TURBOMOLE have to be installed on your system, 104 | either by using ``enviornment modules`` or by placing the executables in `/usr/local/bin`. 105 | 106 | +-----------+-----------------------------------------------------------------------+ 107 | | MNDO99 | | 108 | +-----------+-----------------------------------------------------------------------+ 109 | | DFTB+ | place Slater-Koster parameters `atom-atom.spl` in `/usr/local/dftb+` | 110 | +-----------+-----------------------------------------------------------------------+ 111 | | ORCA | All orca utilities must also be in your path. | 112 | +-----------+-----------------------------------------------------------------------+ 113 | | TURBOMOLE | The ridft and rdgrad programs of Turbomole 7.3 are used. | 114 | +-----------+-----------------------------------------------------------------------+ 115 | 116 | Please contact the development teams of these programs directly for executables since we do not have the 117 | right to distribute them. 118 | -------------------------------------------------------------------------------- /source/requirements.txt: -------------------------------------------------------------------------------- 1 | sphinx==5.3.0 2 | sphinx_rtd_theme==1.2.2 3 | sphinxcontrib-contentui==0.2.5 4 | ablog==0.11.4.post1 5 | sphinx_design==0.5.0 6 | sphinx_copybutton==0.5.2 7 | sphinx_togglebutton==0.3.2 8 | -------------------------------------------------------------------------------- /source/spgfn.rst: -------------------------------------------------------------------------------- 1 | .. _dipro: 2 | 3 | ------------------- 4 | Spin-polarization 5 | ------------------- 6 | 7 | This guide aims to give a general overview of spin-polarized (sp)GFNn-xTB calculations within the ``xtb`` program package. 8 | 9 | .. note:: 10 | This feature is available in ``xtb`` in version 6.6.1 and upward via the tblite. 11 | 12 | 13 | .. contents:: 14 | 15 | General description 16 | =================== 17 | 18 | GFN1-xTB and GFN2-xTB both treat open-shell systems in an restricted open-shell fashion since their energy expressions are spin-independent. 19 | Therefore, higher electron spin multiplicities will always be higher in energy than the low-spin multiplicities. 20 | However, the methods are occupation dependent and the geometries of high-spin states can still be optimized. 21 | 22 | spGFNn-xTB 23 | =========== 24 | To remedy this issue the spin-polarized GFN1 and GFN2-xTB methods (spGFNn-xTB) have been developed and are available in ``xtb`` via the tblite library with the call: 25 | 26 | .. code:: sh 27 | 28 | > xtb --spinpol --tblite 29 | 30 | 31 | .. note:: 32 | The spin polarization will only affect the energies of open-shell configurations and not of singlets 33 | 34 | Example 35 | =================== 36 | 37 | As example we will calculate the spin splittings of a mixed-valence **FeCo** complex with spGFN2-xTB to find the electronic ground state: 38 | 39 | .. tab-set:: 40 | 41 | .. tab-item:: FeCO 42 | 43 | .. figure:: ../figures/spgfn.png 44 | 45 | .. tab-item:: mol.xyz 46 | 47 | .. code-block:: none 48 | 49 | 96 50 | 51 | Co 4.2981 7.8875 -2.4539 52 | Fe 4.2936 7.6860 -0.2490 53 | N 4.3177 8.2394 -4.7611 54 | N 2.5367 8.7591 -2.6654 55 | N 2.3093 8.5146 -0.4585 56 | C 2.8977 8.4151 -5.0518 57 | H 2.4313 7.4287 -5.0575 58 | H 2.7341 8.8807 -6.0379 59 | C 2.1870 9.2538 -3.9732 60 | H 2.4985 10.3023 -4.0724 61 | H 1.1027 9.2137 -4.1534 62 | C 1.8587 9.0585 -1.5831 63 | C 0.5926 9.8363 -1.6028 64 | C -0.5637 9.2492 -1.0959 65 | H -0.5146 8.2451 -0.7007 66 | C -1.7596 9.9421 -1.0971 67 | H -2.6509 9.4763 -0.7029 68 | C -1.8155 11.2325 -1.5975 69 | H -2.7493 11.7751 -1.5960 70 | C -0.6674 11.8282 -2.0926 71 | H -0.7045 12.8389 -2.4730 72 | C 0.5294 11.1352 -2.0985 73 | H 1.4270 11.6140 -2.4622 74 | C 1.9785 8.9213 0.8129 75 | C 1.6789 10.2428 1.1731 76 | H 1.6533 11.0098 0.4144 77 | C 1.4548 10.5742 2.4929 78 | H 1.2329 11.6001 2.7502 79 | C 1.5192 9.6137 3.4891 80 | H 1.3431 9.8845 4.5191 81 | C 1.8213 8.3036 3.1506 82 | H 1.8771 7.5470 3.9204 83 | C 2.0494 7.9614 1.8355 84 | H 2.2654 6.9364 1.5551 85 | C 5.3288 9.1918 1.9786 86 | H 5.5540 8.1404 1.7923 87 | H 5.1441 8.9630 4.0893 88 | N 5.5471 9.4758 -2.5880 89 | N 5.4239 9.4980 -0.3630 90 | C 5.1066 9.4430 -4.9974 91 | H 4.4198 10.2884 -5.0609 92 | H 5.6486 9.3764 -5.9534 93 | C 6.1233 9.7533 -3.8739 94 | H 7.0099 9.1183 -4.0024 95 | H 6.4521 10.7963 -3.9819 96 | C 5.8484 10.0894 -1.4741 97 | C 6.6871 11.3166 -1.4253 98 | C 6.2995 12.4761 -2.0920 99 | H 5.3646 12.4913 -2.6351 100 | C 7.0867 13.6116 -2.0320 101 | H 6.7762 14.5093 -2.5474 102 | C 8.2677 13.6012 -1.3084 103 | H 8.8808 14.4891 -1.2624 104 | C 8.6554 12.4529 -0.6380 105 | H 9.5718 12.4449 -0.0664 106 | C 7.8701 11.3159 -0.6942 107 | H 8.1642 10.4190 -0.1694 108 | C 5.2950 10.0694 0.8789 109 | C 5.0337 11.4236 1.1229 110 | H 4.9714 12.1140 0.2955 111 | C 4.8255 11.8729 2.4115 112 | H 4.6221 12.9211 2.5798 113 | C 4.8647 10.9989 3.4848 114 | H 4.6959 11.3605 4.4876 115 | C 5.1147 9.6533 3.2589 116 | N 5.5409 5.9316 -0.8551 117 | C 6.9688 4.5777 -2.3437 118 | N 5.5363 6.4511 -3.0183 119 | H 6.1674 5.3706 -4.7257 120 | H 6.9044 6.9670 -4.5066 121 | C 4.8934 7.0165 -5.3047 122 | C 5.9719 6.3998 -4.3893 123 | C 6.0308 5.6968 -2.0668 124 | H 4.0923 6.2814 -5.4031 125 | H 5.3284 7.1836 -6.3039 126 | C 6.0102 5.4138 0.3274 127 | C 7.6940 4.5970 1.8539 128 | C 5.0873 5.3600 1.3878 129 | C 5.4599 4.9302 2.6424 130 | C 6.7691 4.5391 2.8839 131 | C 7.3321 5.0289 0.5932 132 | H 8.0785 5.0923 -0.1832 133 | H 8.7188 4.3056 2.0376 134 | H 4.7300 4.8956 3.4388 135 | H 7.0654 4.1993 3.8647 136 | H 4.0598 5.6485 1.1710 137 | C 6.5768 3.2760 -2.0424 138 | C 8.6681 2.4371 -2.8654 139 | C 8.2226 4.7949 -2.9076 140 | H 7.1084 1.2072 -2.0670 141 | H 5.6060 3.1067 -1.6000 142 | C 9.0673 3.7296 -3.1624 143 | C 7.4214 2.2136 -2.3040 144 | H 8.5451 5.8037 -3.1213 145 | H 10.0420 3.9086 -3.5932 146 | H 9.3287 1.6068 -3.0670 147 | 148 | 149 | .. code:: bash 150 | 151 | > xtb mol.xyz --spinpol --tblite --uhf 152 | 153 | with being the number of unparied electrons 0, 2, 4, 6, and 8 (with the correspond multiplicities 1, 3, 5, 7, and 9). The ground state is experimentally known to be a septet. 154 | The total energies in Hartree are shown below: 155 | 156 | 157 | +--------------+----------------------+---------------------+ 158 | | Multiplicity | E(GFN2-xTB) | E(spGFN2-xTB) | 159 | +==============+======================+=====================+ 160 | | 1 | -145.1025 | -145.1025 | 161 | +--------------+----------------------+---------------------+ 162 | | 3 | -145.0996 | -145.1185 | 163 | +--------------+----------------------+---------------------+ 164 | | 5 | -145.0870 | -145.1712 | 165 | +--------------+----------------------+---------------------+ 166 | | 7 | -145.0574 | -145.1904 | 167 | +--------------+----------------------+---------------------+ 168 | | 9 | -144.9653 | -145.1209 | 169 | +--------------+----------------------+---------------------+ 170 | 171 | and the spin-splittings with respect to the septet ground-state in kcal/mol are: 172 | 173 | +--------------+----------------------+---------------------+ 174 | | Multiplicity | ΔE(GFN2-xTB) | ΔE(spGFN2-xTB) | 175 | +==============+======================+=====================+ 176 | | 1 | -28.3 | 55.2 | 177 | +--------------+----------------------+---------------------+ 178 | | 3 | -26.4 | 45.2 | 179 | +--------------+----------------------+---------------------+ 180 | | 5 | -18.5 | 12.1 | 181 | +--------------+----------------------+---------------------+ 182 | | 7 | 0.0 | 0.0 | 183 | +--------------+----------------------+---------------------+ 184 | | 9 | 57.8 | 43.6 | 185 | +--------------+----------------------+---------------------+ 186 | 187 | The correct gound state can be found with spGFN2-xTB but not with GFN2-xTB. 188 | 189 | Please find more information on spGFNn-xTB methods in our publication: 190 | 191 | H. Neugebauer, B. Bädorf, S. Ehlert, A. Hansen, S. Grimme, *J. Comput. Chem.*, **2023**, 44(27), 2120. 192 | `DOI: 10.1002/jcc.27185 `_ 193 | -------------------------------------------------------------------------------- /source/versions.rst: -------------------------------------------------------------------------------- 1 | .. _version: 2 | 3 | ------------------------ 4 | Versions and Changelog 5 | ------------------------ 6 | 7 | .. note:: Release candidates and beta versions are not listed here. 8 | 9 | Version 6.2 10 | - Bugfix: Fukui index calculation 11 | - Bugfix: wrong forces in FIRE optimizer 12 | - Bugfix: $cube instructions were not read 13 | - Bugfix: Input error for ``$gbsa`` data group 14 | - GFN0-xTB Hamiltonian consistent with ChemRxiv preprint 15 | - periodic boundary conditions for GFN0-xTB 16 | - preliminary implicit solvation model GBSA for GFN0-xTB 17 | 18 | Version 6.1.4 19 | - Bugfix: parallisation error in GBSA 20 | 21 | Version 6.1.3 22 | - added FIRE and L-ANCopt as optimization engines 23 | - Bugfix: FOD calculation was using wrong density 24 | 25 | Version 6.1.2 26 | - Bugfix: wrong convergence threshold for RF solver 27 | 28 | Version 6.1.1 29 | - Bugfix: wrong constraining energy in ``xtbscan.log`` 30 | - Bugfix: symmetry finder was inactive 31 | 32 | Version 6.1 33 | - removed ``isotope`` input 34 | - Turbomole ``basis`` and ``mos`` printout 35 | - ORCA GBW file printout 36 | - metadynamics runtyp added 37 | - GFN0-xTB implemented 38 | - completely tunable model Hessian for optimizer 39 | - separated fixing and constraining 40 | - elementwise fixing and constraining 41 | - new geometry summary printout for optimizations 42 | - better printout for optimizer (RMSD, energy gain) 43 | - profiling printout for SCC and optimizer 44 | - adjustable SASA grid for GBSA 45 | - case insensitive solvent strings for GBSA 46 | - Bugfix: mode following printout crashes for large systems (>100 atoms) 47 | 48 | Version 6.0.2 49 | - Bugfix: timings wrapped around 50 | 51 | Version 6.0.1 52 | - additional GFN2-xTB GBSA parameteres added 53 | - Bugfix: ``molden.input`` could not be disabled 54 | - Bugfix: deallocation error in mode following 55 | 56 | Version 6.0 57 | - GFN2-xTB GBSA parameteres added 58 | - internal parameter files 59 | - detailed input 60 | - ``XTBPATH`` variable 61 | - parallel Hessian with GBSA 62 | - logfermi wallpotential added 63 | - sdf input files supported 64 | - automatic Fukui indices and electrophilicity index 65 | -------------------------------------------------------------------------------- /source/xtb_info.rst: -------------------------------------------------------------------------------- 1 | .. _xtb_info: 2 | 3 | ---------------- 4 | Info Submodule 5 | ---------------- 6 | 7 | .. note:: 8 | This feature is only present in version 6.3 and newer 9 | 10 | The info submodule allows to acquire information about the geometry as it 11 | would be processed in a full ``xtb`` run, but without actually performing 12 | a calculation. 13 | 14 | The info submodule is invoked by 15 | 16 | .. code-block:: text 17 | 18 | xtb info [geometry] ... 19 | 20 | and can handle multiple (read several thousand) input files sequentially. 21 | 22 | In the normal run mode, with one input file, the info submodule will show 23 | the number of atoms found, the identifier map and geometry specific information 24 | as printed in the property printout. 25 | These information can be used to verify ``xtb`` will correctly read the input 26 | structure, in case of errors the info submodule will return with a non-zero 27 | exit code. 28 | 29 | The identifier map printed can be used in the detailed input to select certain 30 | group of atoms and is printed to show the found species and mapping in the input 31 | file 32 | 33 | .. code-block:: text 34 | 35 | ID Z sym. atoms 36 | 1 6 C 1, 6-7, 13, 14 37 | 2 7 N 2, 4, 9, 12 38 | 3 6 C* 3, 10 39 | 4 8 18O 8 40 | 5 8 O 11 41 | 6 1 D 15-17 42 | 7 1 H 18-24 43 | 44 | In batch mode, with multiple input files, the info submodule will generate 45 | additional diagnostics regarding the input files 46 | 47 | .. code-block:: text 48 | 49 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 50 | Processed 2474 individual inputs 51 | 11/2474 inputs failed info check( 0.4%) 52 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 53 | 54 | An summary of the errors will be found in the standard output when the 55 | file was processed, in case an error is encounter the info submodule will 56 | return with a non-zero exit code. Processing is not aborted due to errors. 57 | This can be used to validate structures before performing actual calculations. 58 | -------------------------------------------------------------------------------- /source/xtb_ir.rst: -------------------------------------------------------------------------------- 1 | .. _xtb_ir: 2 | 3 | ------------------ 4 | IR Submodule 5 | ------------------ 6 | 7 | .. note:: 8 | This feature will be present in the upcoming release version 6.5.2 9 | 10 | The IR submodule allows to evaluate IR intensities from data produced 11 | in previous calculations. 12 | To run the IR submodule use 13 | 14 | .. code-block:: text 15 | 16 | xtb ir [options] --dftbplus [hessian] --born [borncharges] 17 | 18 | The geometry can be any format accepted by ``xtb``, while the hessian format depends on the 19 | options passed to the IR submodule. Right now, only the projected DFTB+ hessian data group is 20 | available. 21 | 22 | Mandatory keywords are: 23 | 24 | --born 25 | Read a DFTB+ dipole derivatives / born charges ``born.out`` file 26 | 27 | --dftbplus 28 | Read a DFTB+ ``hessian.out`` file, projection will be performed automatically 29 | 30 | Please find additional keywords in the documentation for the ``thermo`` submodule. 31 | IR intensities, sometimes also called *Born charges*, can equivalently be obtained from 32 | 33 | 1. mixed 2nd derivatives of the energy with respect to atomic positions and external 34 | electric field 35 | 2. 1st derivative of dipole moment with respect to atomic positions 36 | 3. 1st derivative of forces with respect to external electric field 37 | 38 | In DFTB+, the second pathway is employed. 39 | This module aims to easen the calculation of SQM solid state IR spectra for large molecular 40 | crystals or organic crystals with very large unit cells, where automated supercell 41 | generation and phonon vibration evaluation is no longer computationally feasible, not even 42 | with SQM methods. Please keep in mind, that these missing lattice vibrations introduce an 43 | unkown error into the low-wavenumber area. 44 | -------------------------------------------------------------------------------- /source/xtb_thermo.rst: -------------------------------------------------------------------------------- 1 | .. _xtb_thermo: 2 | 3 | ------------------ 4 | Thermo Submodule 5 | ------------------ 6 | 7 | .. note:: 8 | This feature is only present in version 6.3 and newer 9 | 10 | The thermo submodule allows to evaluate thermodynamic functions from data produced 11 | in previous calculations, generally the results are equivalent to the ones 12 | produced in a frequency calculation in ``xtb``. 13 | 14 | To run the thermo submodule use 15 | 16 | .. code-block:: text 17 | 18 | xtb thermo [options] [hessian] 19 | 20 | The geometry can be any format accepted by ``xtb``, while the hessian format 21 | depends on the options passed to the thermo submodule. 22 | It defaults to the non-massweigthed, projected Turbomole hessian data group. 23 | 24 | Possible options are: 25 | 26 | --sthr REAL 27 | Rotor cutoff for RRHO partition function in rcm 28 | 29 | --temp REAL 30 | Temperature for thermodynamic functions in K, 31 | takes a comma separated list of temperatures 32 | 33 | --turbomole 34 | Read a Turbomole Hessian file, 35 | use this only when $nomw is not present in control 36 | 37 | --orca 38 | Read a Orca .hess file, projection will be performed automatically 39 | 40 | --dftb+ 41 | Read a DFTB+ hessian.out file, projection will be performed automatically 42 | 43 | An example calculation is given here, reevaluating at a different rotor cutoff 44 | for multiple temperatures 45 | 46 | .. code-block:: text 47 | 48 | xtb benzene.xyz --namespace benzene --ohess 49 | ... 50 | xtb thermo --sthr 100 --temp 50,100,150,200,250,300 benzene.xtbopt.xyz benzene.hessian 51 | ... 52 | 53 | Molecule has the following symmetry elements: (i) (C6) (C3) 7*(C2) (S6) (S3) 7*(sigma) 54 | It seems to be the D6h point group 55 | d6h symmetry found (for desy threshold: 0.10E+00) used in thermo 56 | 57 | ... 58 | 59 | T/K H(0)-H(T)+PV H(T)/Eh T*S/Eh G(T)/Eh 60 | ------------------------------------------------------------------------ 61 | 50.00 0.633464E-03 0.981387E-01 0.362609E-02 0.945126E-01 62 | 100.00 0.128528E-02 0.987905E-01 0.815319E-02 0.906373E-01 63 | 150.00 0.203561E-02 0.995409E-01 0.131373E-01 0.864036E-01 64 | 200.00 0.296494E-02 0.100470E+00 0.185801E-01 0.818901E-01 65 | 250.00 0.413423E-02 0.101639E+00 0.245239E-01 0.771156E-01 66 | 300.00 0.558192E-02 0.103087E+00 0.310070E-01 0.720801E-01 (used) 67 | ------------------------------------------------------------------------ 68 | 69 | ... 70 | -------------------------------------------------------------------------------- /source/xtb_topo.rst: -------------------------------------------------------------------------------- 1 | .. _xtb_topo: 2 | 3 | -------------------- 4 | Topology Submodule 5 | -------------------- 6 | 7 | .. note:: 8 | This feature is only present in version 6.3 and newer 9 | 10 | The topology submodule allows to create a GFN-FF topology from a geometry 11 | input, which can be used to restart a calculation with the GFN-FF without 12 | having to perform a costly reevaluation of the force field topology 13 | 14 | To start the generation use 15 | 16 | .. code-block:: text 17 | 18 | xtb topo [--namspace ] 19 | 20 | If you want to use a particular namespace in the calculation later include 21 | the namespace flag. 22 | Note that even if you want to perform several GFN-FF calculation on different 23 | namespaces, generate the topology file without a namespace is recommend, 24 | as ``xtb`` will first search the local namespace and than fall back to the 25 | default file name to finding the generated topology file. 26 | 27 | .. important:: 28 | The force field generation step is a cubic scaling step as it requires 29 | an all pair shortest path (APSP) algorithm for generating the topological 30 | charges and for the diagonalization of the Hückel matrices for the 31 | torsion potentials, which can take, depending on the system of interest 32 | a significant portion of computation time. 33 | 34 | The generated file will be named ``gfnff_topo`` or ``.gfnff_topo`` and 35 | can become quite large. 36 | --------------------------------------------------------------------------------