{ "cells": [ { "cell_type": "markdown", "id": "312d59a5", "metadata": {}, "source": [ "# Program structure" ] }, { "cell_type": "code", "execution_count": 1, "id": "984c876f", "metadata": { "scrolled": true }, "outputs": [], "source": [ "import veloxchem as vlx" ] }, { "cell_type": "markdown", "id": "ab48cf37", "metadata": {}, "source": [ "The VeloxChem program adopts a layered Python/C++ language structure. \n", "\n", "```{image} ../images/code-structure.png\n", ":alt: veloxchem-structure\n", ":class: bg-primary mb-1\n", ":width: 600px\n", ":align: center\n", "```\n", "\n", "You can use the standard functions to get a more detailed view of the Python layer. The `help` function will give you a package description, stating the copyright agreement." ] }, { "cell_type": "code", "execution_count": 2, "id": "e5718d36", "metadata": { "tags": [ "output_scroll" ] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Help on package veloxchem:\n", "\n", "NAME\n", " veloxchem\n", "\n", "DESCRIPTION\n", " # VELOXCHEM\n", " # ----------------------------------------------------\n", " # An Electronic Structure Code\n", " #\n", " # SPDX-License-Identifier: BSD-3-Clause\n", " #\n", " # Copyright 2018-2025 VeloxChem developers\n", " #\n", " # Redistribution and use in source and binary forms, with or without modification,\n", " # are permitted provided that the following conditions are met:\n", " #\n", " # 1. Redistributions of source code must retain the above copyright notice, this\n", " # list of conditions and the following disclaimer.\n", " # 2. Redistributions in binary form must reproduce the above copyright notice,\n", " # this list of conditions and the following disclaimer in the documentation\n", " # and/or other materials provided with the distribution.\n", " # 3. Neither the name of the copyright holder nor the names of its contributors\n", " # may be used to endorse or promote products derived from this software without\n", " # specific prior written permission.\n", " #\n", " # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND\n", " # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED\n", " # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\n", " # DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE\n", " # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\n", " # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR\n", " # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n", " # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT\n", " # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT\n", " # OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n", "\n", "PACKAGE CONTENTS\n", " __main__\n", " aodensitymatrix\n", " aoindices\n", " atomtypeidentifier\n", " batchsize\n", " blockdavidson\n", " c2diis\n", " c6driver\n", " checkpoint\n", " cli\n", " conformergenerator\n", " cpcmdriver\n", " cphfsolver\n", " cppsolver\n", " cubicgrid\n", " cubicresponsedriver\n", " densityviewer\n", " dftutils\n", " dispersionmodel\n", " distributedarray\n", " embedding\n", " environment\n", " errorhandler\n", " evbdataprocessing\n", " evbdriver\n", " evbfepdriver\n", " evbffbuilder\n", " evbreporter\n", " evbsystembuilder\n", " excitedstateanalysisdriver\n", " excitondriver\n", " features\n", " firstorderprop\n", " fockdriver\n", " gradientdriver\n", " griddriver\n", " hessiandriver\n", " hessianorbitalresponse\n", " imdatabasedriver\n", " imdatabasepointcollecter\n", " imforcefieldgenerator\n", " impescoordinates\n", " impesdriver\n", " inputparser\n", " interpolationdatapoint\n", " interpolationdriver\n", " linearsolver\n", " lreigensolver\n", " lrsolver\n", " main\n", " matrices\n", " matrix\n", " mklconf\n", " mmdriver\n", " mmforcefieldgenerator\n", " mmgradientdriver\n", " mofbuilder\n", " mofoptimizer\n", " mofpreparer\n", " mofutils\n", " mointsdriver\n", " molecularbasis\n", " molecularorbitals\n", " molecule\n", " mp2driver\n", " mpitask\n", " nonlinearsolver\n", " numerovdriver\n", " oneeints\n", " openmmdriver\n", " openmmdynamics\n", " openmmgradientdriver\n", " optimizationdriver\n", " optimizationengine\n", " orbitalviewer\n", " outputstream\n", " peforcefieldgenerator\n", " polarizabilitygradient\n", " polorbitalresponse\n", " profiler\n", " pulsedrsp\n", " quadraticresponsedriver\n", " reactionmatcher\n", " respchargesdriver\n", " rifockdriver\n", " rigradientdriver\n", " rspabsorption\n", " rspc6\n", " rspcdspec\n", " rspcustomproperty\n", " rsplinabscross\n", " rsppolarizability\n", " rspproperty\n", " rspshg\n", " rsptpa\n", " rsptpatransition\n", " sadguessdriver\n", " sanitychecks\n", " scfdriver\n", " scfgradientdriver\n", " scfhessiandriver\n", " scfrestdriver\n", " scfrestopendriver\n", " scfunrestdriver\n", " seminario\n", " shgdriver\n", " solvationbuilder\n", " solvationfepdriver\n", " subcommunicators\n", " submatrix\n", " symmetryanalyzer\n", " symmetryoperations\n", " tdacppsolver\n", " tdaeigensolver\n", " tddftgradientdriver\n", " tddftorbitalresponse\n", " tdhfhessiandriver\n", " threepatransitiondriver\n", " tpadriver\n", " tpafulldriver\n", " tpareddriver\n", " tpatransitiondriver\n", " trajectorydriver\n", " uffparameters\n", " veloxchemlib\n", " vibrationalanalysis\n", " visualizationdriver\n", " xtbdriver\n", " xtbgradientdriver\n", " xtbhessiandriver\n", "\n", "FUNCTIONS\n", " available_functionals(...) method of builtins.PyCapsule instance\n", " available_functionals() -> list[str]\n", "\n", " Gets a list of available exchange-correlation functionals.\n", "\n", " available_pdft_functionals(...) method of builtins.PyCapsule instance\n", " available_pdft_functionals() -> list[str]\n", "\n", " Gets a list of available pdft exchange-correlation functionals components.\n", "\n", " bohr_in_angstrom(...) method of builtins.PyCapsule instance\n", " bohr_in_angstrom() -> float\n", "\n", " Gets Bohr value in Angstroms.\n", "\n", " chemical_element_identifier(...) method of builtins.PyCapsule instance\n", " chemical_element_identifier(arg0: str) -> int\n", "\n", " Gets chemical element identifier.\n", "\n", " chemical_element_label(...) method of builtins.PyCapsule instance\n", " chemical_element_label(arg0: int) -> str\n", "\n", " Gets chemical element label.\n", "\n", " chemical_element_mass(...) method of builtins.PyCapsule instance\n", " chemical_element_mass(arg0: int) -> float\n", "\n", " Gets chemical element mass.\n", "\n", " chemical_element_max_angular_momentum(...) method of builtins.PyCapsule instance\n", " chemical_element_max_angular_momentum(arg0: int) -> int\n", "\n", " Gets maximum angular momentum of atomic shell in chemical element.\n", "\n", " chemical_element_name(...) method of builtins.PyCapsule instance\n", " chemical_element_name(arg0: int) -> str\n", "\n", " Gets chemical element name.\n", "\n", " compute_angular_momentum_integrals(...) method of builtins.PyCapsule instance\n", " compute_angular_momentum_integrals(molecule: veloxchem.veloxchemlib.Molecule, basis: veloxchem.veloxchemlib.MolecularBasis, origin: list[float] = [0.0, 0.0, 0.0]) -> list\n", "\n", " Computes angular momentum integrals.\n", "\n", " compute_linear_momentum_integrals(...) method of builtins.PyCapsule instance\n", " compute_linear_momentum_integrals(molecule: veloxchem.veloxchemlib.Molecule, basis: veloxchem.veloxchemlib.MolecularBasis) -> list\n", "\n", " Computes linear momentum integrals.\n", "\n", " dipole_in_debye(...) method of builtins.PyCapsule instance\n", " dipole_in_debye() -> float\n", "\n", " Gets convertion factor for dipole moment (a.u. -> Debye).\n", "\n", " extinction_coefficient_from_beta(...) method of builtins.PyCapsule instance\n", " extinction_coefficient_from_beta() -> float\n", "\n", " Gets factor needed for the calculation of the extinction coefficent from the electric-dipole magnetic-dipole polarizability beta.\n", "\n", " fine_structure_constant(...) method of builtins.PyCapsule instance\n", " fine_structure_constant() -> float\n", "\n", " Gets fine-structure constant.\n", "\n", " hartree_in_ev(...) method of builtins.PyCapsule instance\n", " hartree_in_ev() -> float\n", "\n", " Gets Hartree value in electronvolts.\n", "\n", " hartree_in_kcalpermol(...) method of builtins.PyCapsule instance\n", " hartree_in_kcalpermol() -> float\n", "\n", " Gets Hartree value in kcal/mol.\n", "\n", " hartree_in_kjpermol(...) method of builtins.PyCapsule instance\n", " hartree_in_kjpermol() -> float\n", "\n", " Gets Hartree value in kJ/mol.\n", "\n", " hartree_in_wavenumber(...) method of builtins.PyCapsule instance\n", " hartree_in_wavenumber() -> float\n", "\n", " Gets Hartree value in reciprocal cm.\n", "\n", " hartree_in_wavenumbers(...) method of builtins.PyCapsule instance\n", " hartree_in_wavenumbers() -> float\n", "\n", " Gets Hartree value in reciprocal cm.\n", "\n", " is_chemical_element(...) method of builtins.PyCapsule instance\n", " is_chemical_element(arg0: int) -> bool\n", "\n", " Checks if identifier is chemical element number.\n", "\n", " make_matrices(...) method of builtins.PyCapsule instance\n", " make_matrices(*args, **kwargs)\n", " Overloaded function.\n", "\n", " 1. make_matrices(arg0: int, arg1: CMolecularBasis, arg2: veloxchem.veloxchemlib.mat_t) -> CMatrices\n", "\n", " Creates matrices for given basis.\n", "\n", " 2. make_matrices(arg0: Annotated[list[int], FixedSize(2)], arg1: CMolecularBasis, arg2: veloxchem.veloxchemlib.mat_t) -> CMatrices\n", "\n", " Creates matrices for given basis.\n", "\n", " 3. make_matrices(arg0: Annotated[list[int], FixedSize(3)], arg1: CMolecularBasis, arg2: veloxchem.veloxchemlib.mat_t) -> CMatrices\n", "\n", " Creates matrices for given basis.\n", "\n", " 4. make_matrices(arg0: Annotated[list[int], FixedSize(4)], arg1: CMolecularBasis, arg2: veloxchem.veloxchemlib.mat_t) -> CMatrices\n", "\n", " Creates matrices for given basis.\n", "\n", " 5. make_matrices(arg0: int, arg1: CMolecularBasis, arg2: CMolecularBasis) -> CMatrices\n", "\n", " Creates matrices for given basis.\n", "\n", " 6. make_matrices(arg0: Annotated[list[int], FixedSize(2)], arg1: CMolecularBasis, arg2: CMolecularBasis) -> CMatrices\n", "\n", " Creates matrices for given basis.\n", "\n", " 7. make_matrices(arg0: Annotated[list[int], FixedSize(3)], arg1: CMolecularBasis, arg2: CMolecularBasis) -> CMatrices\n", "\n", " Creates matrices for given basis.\n", "\n", " 8. make_matrices(arg0: Annotated[list[int], FixedSize(4)], arg1: CMolecularBasis, arg2: CMolecularBasis) -> CMatrices\n", "\n", " Creates matrices for given basis.\n", "\n", " make_matrix(...) method of builtins.PyCapsule instance\n", " make_matrix(*args, **kwargs)\n", " Overloaded function.\n", "\n", " 1. make_matrix(arg0: CMolecularBasis, arg1: veloxchem.veloxchemlib.mat_t) -> CMatrix\n", "\n", " Creates matrix for given basis.\n", "\n", " 2. make_matrix(arg0: CMolecularBasis, arg1: CMolecularBasis) -> CMatrix\n", "\n", " Creates matrix for given pair of bases.\n", "\n", " mpi_master(...) method of builtins.PyCapsule instance\n", " mpi_master() -> int\n", "\n", " Gets the rank of MPI master process.\n", "\n", " parse_xc_func(...) method of builtins.PyCapsule instance\n", " parse_xc_func(xcLabel: str) -> veloxchem.veloxchemlib.XCFunctional\n", "\n", " Converts exchange-correlation functional label to exchange-correlation functional object.\n", "\n", " partition_atoms(...) method of builtins.PyCapsule instance\n", " partition_atoms(arg0: int, arg1: int, arg2: int) -> list[int]\n", "\n", " Get atomic indices of partitioned atoms list.\n", "\n", " rotatory_strength_in_cgs(...) method of builtins.PyCapsule instance\n", " rotatory_strength_in_cgs() -> float\n", "\n", " Gets convertion factor for rotatory strength (a.u. -> 10^-40 cgs).\n", "\n", "DATA\n", " __deployed__ = {'author': 'Xin Li', 'build': '195', 'commit': '645f537...\n", "\n", "VERSION\n", " 1.0rc3\n", "\n", "FILE\n", " /Users/lixin/miniforge3/envs/vlxman2/lib/python3.12/site-packages/veloxchem/__init__.py\n", "\n", "\n" ] } ], "source": [ "help(vlx)" ] }, { "cell_type": "markdown", "id": "5e2aeae3", "metadata": {}, "source": [ "## Classes\n", "\n", "The functionality of VeloxChem is built into the classes it implements. An overview of the available classes is provided with the `dir` function." ] }, { "cell_type": "code", "execution_count": 7, "id": "8634b6fd", "metadata": { "tags": [ "output_scroll" ] }, "outputs": [ { "data": { "text/plain": [ "['AODensityMatrix',\n", " 'AOFockMatrix',\n", " 'Absorption',\n", " 'AtomBasis',\n", " 'BasisFunction',\n", " 'BlockDavidsonSolver',\n", " 'C6',\n", " 'C6Solver',\n", " 'CircularDichroismSpectrum',\n", " 'ComplexResponse',\n", " 'CubicGrid',\n", " 'CustomProperty',\n", " 'DenseMatrix',\n", " 'DispersionModel',\n", " 'ElectricDipoleIntegralsDriver',\n", " 'ElectronRepulsionIntegralsDriver',\n", " 'ExcitationVector',\n", " 'ExcitonModelDriver',\n", " 'InputParser',\n", " 'KineticEnergyIntegralsDriver',\n", " 'LinearAbsorptionCrossSection',\n", " 'LinearResponseEigenSolver',\n", " 'LinearResponseSolver',\n", " 'LoPropDriver',\n", " 'MOIntegralsDriver',\n", " 'MOIntsBatch',\n", " 'MolecularBasis',\n", " 'MolecularOrbitals',\n", " 'Molecule',\n", " 'Mp2Driver',\n", " 'MpiTask',\n", " 'NuclearPotentialIntegralsDriver',\n", " 'OptimizationDriver',\n", " 'OutputStream',\n", " 'OverlapIntegralsDriver',\n", " 'Polarizability',\n", " 'ResponseDriver',\n", " 'ResponseProperty',\n", " 'SADGuessDriver',\n", " 'ScfFirstOrderProperties',\n", " 'ScfGradientDriver',\n", " 'ScfRestrictedDriver',\n", " 'ScfUnrestrictedDriver',\n", " 'SubCommunicators',\n", " 'TDAExciDriver',\n", " 'TwoIndexes',\n", " 'VisualizationDriver',\n", " 'XTBDriver',\n", " 'XTBGradientDriver',\n", " '__builtins__',\n", " '__cached__',\n", " '__deployed__',\n", " '__doc__',\n", " '__file__',\n", " '__loader__',\n", " '__name__',\n", " '__package__',\n", " '__path__',\n", " '__spec__',\n", " '__version__',\n", " 'ao_matrix_to_dalton',\n", " 'ao_matrix_to_veloxchem',\n", " 'aodensitymatrix',\n", " 'aofockmatrix',\n", " 'assert_msg_critical',\n", " 'batchsize',\n", " 'blockdavidson',\n", " 'bohr_in_angstroms',\n", " 'c2diis',\n", " 'c6solver',\n", " 'checkpoint',\n", " 'cppsolver',\n", " 'cubicgrid',\n", " 'denguess',\n", " 'denmat',\n", " 'deprecations',\n", " 'distributedarray',\n", " 'environ',\n", " 'ericut',\n", " 'errorhandler',\n", " 'excitondriver',\n", " 'fockmat',\n", " 'get_basis_path',\n", " 'get_qq_scheme',\n", " 'get_qq_type',\n", " 'gradientdriver',\n", " 'hartree_in_ev',\n", " 'hartree_in_kcalpermol',\n", " 'inputparser',\n", " 'linearsolver',\n", " 'loprop',\n", " 'lreigensolver',\n", " 'lrsolver',\n", " 'mathconst_pi',\n", " 'moints',\n", " 'mointsdriver',\n", " 'molecularbasis',\n", " 'molecularorbitals',\n", " 'molecule',\n", " 'molorb',\n", " 'mp2driver',\n", " 'mpi_initialized',\n", " 'mpi_master',\n", " 'mpitask',\n", " 'optimizationdriver',\n", " 'optimizationengine',\n", " 'outputstream',\n", " 'profiler',\n", " 'qqscheme',\n", " 'rspabsorption',\n", " 'rspc6',\n", " 'rspcdspec',\n", " 'rspcustomproperty',\n", " 'rspdriver',\n", " 'rsplinabscross',\n", " 'rsppolarizability',\n", " 'rspproperty',\n", " 'scfdriver',\n", " 'scffirstorderprop',\n", " 'scfgradientdriver',\n", " 'scfrestdriver',\n", " 'scfunrestdriver',\n", " 'set_omp_num_threads',\n", " 'set_vlxbasispath',\n", " 'signalhandler',\n", " 'subcommunicators',\n", " 'szblock',\n", " 'tdaexcidriver',\n", " 'tpadriver',\n", " 'tpafulldriver',\n", " 'tpareddriver',\n", " 'veloxchemlib',\n", " 'visualizationdriver',\n", " 'xtbdriver',\n", " 'xtbgradientdriver']" ] }, "execution_count": 7, "metadata": {}, "output_type": "execute_result" } ], "source": [ "dir(vlx)" ] }, { "cell_type": "markdown", "id": "ac3f5f28", "metadata": {}, "source": [ "Information about a specific class is available from the docstring." ] }, { "cell_type": "code", "execution_count": 11, "id": "e6abf4b5", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\n", " Implements spin unrestricted open shell SCF method with C2-DIIS and\n", " two-level C2-DIIS convergence accelerators.\n", "\n", " :param comm:\n", " The MPI communicator.\n", " :param ostream:\n", " The output stream.\n", " \n" ] } ], "source": [ "print(vlx.ScfUnrestrictedDriver.__doc__)" ] }, { "cell_type": "markdown", "id": "b9a93350", "metadata": {}, "source": [ "## Methods and properties\n", "\n", "The actual calculations are performed by the methods in the classes. To list the properties and methods of a class, the `dir` function can be used as follows." ] }, { "cell_type": "code", "execution_count": 8, "id": "5234a031", "metadata": { "scrolled": true, "tags": [ "output_scroll" ] }, "outputs": [ { "data": { "text/plain": [ "['__class__',\n", " '__delattr__',\n", " '__dict__',\n", " '__dir__',\n", " '__doc__',\n", " '__eq__',\n", " '__format__',\n", " '__ge__',\n", " '__getattribute__',\n", " '__gt__',\n", " '__hash__',\n", " '__init__',\n", " '__init_subclass__',\n", " '__le__',\n", " '__lt__',\n", " '__module__',\n", " '__ne__',\n", " '__new__',\n", " '__reduce__',\n", " '__reduce_ex__',\n", " '__repr__',\n", " '__setattr__',\n", " '__sizeof__',\n", " '__str__',\n", " '__subclasshook__',\n", " '__weakref__',\n", " 'add_iter_data',\n", " 'check_convergence',\n", " 'comp_2e_fock',\n", " 'comp_2e_fock_single_comm',\n", " 'comp_2e_fock_split_comm',\n", " 'comp_density_change',\n", " 'comp_diis',\n", " 'comp_energy',\n", " 'comp_full_fock',\n", " 'comp_gradient',\n", " 'comp_guess_density',\n", " 'comp_npot_mat_split_comm',\n", " 'comp_one_ints',\n", " 'compute',\n", " 'compute_s2',\n", " 'delete_mos',\n", " 'gen_molecular_orbitals',\n", " 'gen_new_density',\n", " 'get_acc_type',\n", " 'get_dyn_threshold',\n", " 'get_effective_fock',\n", " 'get_guess_type',\n", " 'get_qq_dyn',\n", " 'get_scaled_fock',\n", " 'get_scf_energy',\n", " 'get_scf_range',\n", " 'get_scf_type',\n", " 'graceful_exit',\n", " 'need_graceful_exit',\n", " 'print_energy_components',\n", " 'print_ground_state',\n", " 'print_header',\n", " 'print_iter_data',\n", " 'print_scf_energy',\n", " 'print_scf_finish',\n", " 'print_scf_title',\n", " 'set_skip_iter_flag',\n", " 'store_diis_data',\n", " 'update_fock_type',\n", " 'update_mol_orbs_phase',\n", " 'update_settings',\n", " 'write_checkpoint']" ] }, "execution_count": 8, "metadata": {}, "output_type": "execute_result" } ], "source": [ "dir(vlx.ScfRestrictedDriver)" ] } ], "metadata": { "celltoolbar": "Tags", "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.12.9" } }, "nbformat": 4, "nbformat_minor": 5 }