update docs

Author: Vishikh Athavale

docs/source/Feature-XLBOMD.rst

@@ -3,17 +3,16 @@ Extended Lagrangian Born Oppenheimer Molecular Dynamics (XL-BOMD)
 
 Extended Lagrangian Born–Oppenheimer Molecular Dynamics (XL-BOMD) improves upon traditional Born–Oppenheimer Molecular Dynamics (BOMD) by introducing auxiliary dynamical variables that track the electronic density matrix in a harmonic potential. This reduces the need for fully converged self-consistent field (SCF) calculations at each time step.
 
-The method enables energy-conserving dynamics even with relaxed SCF convergence, significantly lowering computational cost while maintaining stability. XL-BOMD is particularly effective for long-time simulations and large molecular systems, and is well-suited for semiempirical, Hartree–Fock, and DFT-based electronic structure methods.
+The method enables energy-conserving dynamics even with relaxed SCF convergence, significantly lowering computational cost while maintaining stability. XL-BOMD is particularly effective for long-time simulations and large molecular systems.
 
-This implementation supports efficient simulations by reducing the number of SCF iterations required per time step, enabling practical quantum-based molecular dynamics for systems where conventional BOMD would be prohibitively expensive.
-
-PYSEQM provides two variants:
+PYSEQM provides two variants of XL-BOMD:
 
 - **XL_BOMD**  
   Base extended‐Lagrangian Born–Oppenheimer MD.
 
 - **KSA_XL_BOMD**  
-  Krylov‐subspace‐approximated XL‐BOMD with low‐rank electronic updates (more accurate dynamics without sacrificing speed).
+  An improved Krylov subspace approximation (KSA) scheme for the integration of the electronic equations of motion within XL-BOMD
+  (more accurate dynamics without sacrificing speed).
 
 
 Driver Classes & Initialization
@@ -42,35 +41,47 @@ Import the drivers and instantiate with common arguments:
    ).to(device)
 
    # 2. KSA-XL-BOMD (low-rank Krylov approximation)
-   ksa_params = {
+   xl_bomd_params = {
        'k':             6,        # dissipative force coefficient
-       'max_rank':      3,        # Krylov subspace rank
+       'max_rank':      3,        # Krylov subspace approximation kernel rank
        'err_threshold': 0.0,      # approximation error tolerance
        'T_el':         1500       # electronic temperature (K)
    }
    md_ksa = KSA_XL_BOMD(
-       xl_bomd_params=ksa_params,
+       xl_bomd_params=xl_bomd_params,
        damp=100.0,                # optional, if needed, damping constant (fs) for Langevin dynamics 
        seqm_parameters=seqm_parameters,
        Temp=400.0,
        timestep=0.4,
        output=output
    ).to(device)
 
-Key Parameters
-~~~~~~~~~~~~~~
-- **xl_bomd_params['k']** (`float`)  
-  Controls the strength of the dissipative electronic force `Niklasson, Anders, et al., The Journal of Chemical Physics 130.21 (2009) <https://aip.scitation.org/doi/full/10.1063/1.3148075>`_.
+Key Parameters of XL-BOMD
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The XL-BOMD drivers need a dictionary that specify the parameters for XL-BOMD dynamics. In the above code, this dictionary is `xl_bomd_params`.
+The key/value pairs for this dictionary are:
+
+- **'k'** (`int`)  
+  Controls `K` of the dissipative electronic force. See `Niklasson, Anders, et al., The Journal of Chemical Physics 130.21 (2009) <https://aip.scitation.org/doi/full/10.1063/1.3148075>`_.
 
-- **max_rank** (`int`, KSA only)  
-  Maximum rank of the Krylov subspace used in the low‐rank update.
+  Values from ``3`` to ``9`` are accepted.
 
-- **err_threshold** (`float`, KSA only)  
+- **'max_rank'** (`int`, KSA only)  
+  Maximum rank of the kernel for the update in the Krylov subspace approximation.
+
+- **'err_threshold'** (`float`, KSA only)  
   Error tolerance for the low‐rank approximation (set to 0.0 to fix at `max_rank`).
 
-- **T_el** (`float`, KSA only)  
+- **'T_el'** (`float`, KSA only)  
   Electronic “temperature” for thermalized Hartree–Fock.
 
+The parameters to initialize the MD drivers `XL_BOMD()` and `KSA_XL_BOMD()` are the same as those for `Molecular_Dynamics_Basic()` as in :ref:`bomd_driver`.
+The extra parameters you can specify for XL-BOMD drivers are:
+
+- **xl_bomd_params** (`dict`)
+  The dictionary that specifes the parameters for XL-BOMD dynamics, as described above.
+
 - **damp** (`float`)  
   If you want to run Langevin dynamics, then specify the damping constant `damp` in fs. Langevin dynamics is turned off by default.
 

docs/source/Initialization.rst

@@ -10,7 +10,7 @@ Supported Molecular Input Formats
 You can supply molecular data (atoms and coordinates) in two ways:
 
 - **PyTorch tensors** (in-memory, zero-padded batches)  
-- **`.xyz` files** (read and padded automatically)
+- **.xyz files** (read and padded automatically)
 
 
 Using PyTorch Tensors
@@ -66,8 +66,8 @@ An `.xyz` file includes:
 2. Comment or title (second line)
 3. Atom symbol and coordinates per line (x, y, z)
 
-Use `read_xyz` to load and pad.
-The `read_xyz` function returns numpy tensors (species and coordinates) that have to be converted to PyTorch tensors
+Use `read_xyz(...)` to load and pad.
+The `read_xyz(...)` function returns numpy tensors (species and coordinates) that have to be converted to PyTorch tensors
 
 .. code-block:: python
 
@@ -147,7 +147,7 @@ These imports provide the core components needed to define molecules and access
     from seqm.seqm_functions.constants import Constants
     from seqm.Molecule import Molecule
 
-**Required if reading molecular structures from a `.xyz` file:**
+**Required if reading molecular structures from .xyz files:**
 
 Use this to load molecular geometries from `.xyz` files
 
@@ -179,12 +179,15 @@ Includes stochastic and frictional forces to model interaction with a heat bath,
 
     from seqm.MolecularDynamics import Molecular_Dynamics_Langevin
 
-**Required for KSA-XL Born-Oppenheimer Molecular Dynamics:**
+**Required for Extended-Lagrangian Born-Oppenheimer Molecular Dynamics:**
 
-Implements an efficient Born-Oppenheimer MD scheme using extended Lagrangian and Krylov subspace methods for long, accurate simulations on quantum surfaces.
+Implements an extended Lagrangian Born-Oppenheimer MD (XL-BOMD) scheme and an improved Krylov subspace approximation (KSA) scheme for the integration of the electronic equations of motion within XL-BOMD termed as KSA-XL-BOMD for long, accurate MD simulations.
 
 .. code-block:: python
 
+    # basic XL-BOMD
+    from seqm.MolecularDynamics import XL_BOMD
+    # XL-BOMD with Krylov subspace approximation for the integration of the electronic equations of motion
     from seqm.MolecularDynamics import KSA_XL_BOMD
 
 
@@ -197,7 +200,7 @@ Implements an efficient Born-Oppenheimer MD scheme using extended Lagrangian and
 SEQM Parameters
 ---------------
 
-The ``seqm_parameters`` dictionary defines settings for a semiempirical quantum mechanics (SEQM) simulation.
+The ``seqm_parameters`` dictionary helps you give the specifications for the semiempirical quantum mechanics (SEQM) calculation.
 Below is a typical configuration:
 
 .. code-block:: python
@@ -207,9 +210,10 @@ Below is a typical configuration:
         'scf_eps': 1.0e-6,
         'scf_converger': [2,],
         'sp2': [False, 1.0e-5],
+        ...
     }
 
-Some of the basic parameters in the ``seqm_parameters`` dictionary are:
+Some of the basic key/value pairs in the ``seqm_parameters`` dictionary are:
 
 **method**  (`str`)
     Specifies the semiempirical model to use.
@@ -220,10 +224,10 @@ Some of the basic parameters in the ``seqm_parameters`` dictionary are:
     Convergence threshold for the SCF (Self-Consistent Field) loop.
     The SCF iteration stops when the energy difference between steps is less than this value.
 
-    :recommended: 1e-5 for single point SCF, 1e-8 for excited state calculations
+    :recommended: ``1e-5`` for single-point SCF, ``1e-8`` for excited-state calculations
 
 **scf_converger** (`list`) 
-    Specifies the alorithm used to update the density matrix to converge SCF.
+    Specifies the alorithm and other details that will be used to update the density matrix to converge SCF.
 
     Available options:
 
@@ -232,7 +236,7 @@ Some of the basic parameters in the ``seqm_parameters`` dictionary are:
       Constant linear mixing of the density matrix:  
 
       ``P_new = alpha * P_old + (1 - alpha) * P_candidate``  
-      where ``alpha`` is the mixing coefficient (e.g., 0.2).
+      where ``alpha`` is the mixing coefficient (e.g., ``0.2``).
 
     - ``[1]``  
 
@@ -257,7 +261,7 @@ Some of the basic parameters in the ``seqm_parameters`` dictionary are:
     :format: ``[enabled, tolerance]``  
 
     * ``enabled`` (`bool`): Whether to activate SP2
-    * ``tolerance`` (`float`): SP2 threshold. Recommened between 1e-3 to 1e-7
+    * ``tolerance`` (`float`): SP2 threshold. Recommened between ``1e-3`` to ``1e-7`` for double-precision calculations
 
 **eig**  (`bool`)
     Optional parameter to control whether to compute molecular orbitals after SCF convergence.

docs/source/bomd.rst

@@ -13,30 +13,28 @@ PYSEQM had MD engines for:
 - **Born–Oppenheimer MD** via `Molecular_Dynamics_Basic`  
 - **Langevin-thermostatted dynamics** via `Molecular_Dynamics_Langevin`
 
+.. _bomd_driver:
+
 BOMD driver
 ~~~~~~~~~~~~~~~~~
 Call the BOMD engine using
 
 .. code-block:: python
 
-   from seqm.MolecularDynamics import (
-       Molecular_Dynamics_Basic,
-       Molecular_Dynamics_Langevin
-   )
+   from seqm.MolecularDynamics import Molecular_Dynamics_Basic
 
-   # Basic BOMD
-   md = Molecular_Dynamics_Basic( seqm_parameters=seqm_parameters, Temp=300.0,
+   md = Molecular_Dynamics_Basic(seqm_parameters=seqm_parameters, Temp=300.0,
                                   timestep=0.5, output=output).to(device)
 
 The parameters of `Molecular_Dynamics_Basic` are:
 
-- `seqm_parameters` (`dict`)
+- ``seqm_parameters`` (`dict`)
 
-- `Temp` (`float`) Specify the inital temperature (K) for BOMD. Given the initial temperature in BOMD, the initial nuclear velocities are set by drawing from a Maxwell–Boltzmann distribution so that each degree of freedom has an average kinetic energy of ½ kT
+- ``Temp`` (`float`) Specify the inital temperature (K) for BOMD. Given the initial temperature in BOMD, the initial nuclear velocities are set by drawing from a Maxwell–Boltzmann distribution so that each degree of freedom has an average kinetic energy of ½ kT
 
-- `timestep` (`float`) Integration step size (fs)
+- ``timestep`` (`float`) Integration step size (fs)
 
-- `output`: (`dict`) controlling prints & file dumps, see below
+- ``output``: (`dict`) controlling prints & file dumps, see below
 
 Langevin dynamics
 ~~~~~~~~~~~~~~~~~
@@ -74,13 +72,15 @@ Call the Langevin dynamics engine using
 
 .. code-block:: python
 
+   from seqm.MolecularDynamics import Molecular_Dynamics_Langevin
+
    md_langevin = Molecular_Dynamics_Langevin( damp=100.0, seqm_parameters=seqm_parameters,
                                               Temp=300.0, timestep=0.5, 
                                               output=output).to(device)
 
 In addition to the same parameters as `Molecular_Dynamics_Basic`, `Molecular_Dynamics_Langevin` has the following parameter(s):
 
-- `damp` (`float`) Damping constant in fs
+- ``damp`` (`float`) Damping constant in fs
 
 Configuring Outputs from BOMD
 -----------------------------
@@ -109,7 +109,7 @@ In addition to specifying :ref:`seqm-parameters`, the MD engines also require an
 
 - **prefix** (`str`)  
   Path prefix for all output files.  
-  If you set prefix to `'my_output'`, files will be named like ``./my_output.{molid}.xyz``, etc.
+  If you set prefix to `'my_output'`, then output files will be named like ``./my_output.{molid}.xyz``, etc.
 
 Running the MD Simulation
 --------------------------
@@ -134,6 +134,7 @@ Parameters:
 
 - **remove_com** (`[bool, int]`)  
   Control removal of center‐of‐mass motion:  
+
   - First element (`bool`): whether to remove COM drift.  
   - Second element (`int`): how often to apply it (every N steps).
 

docs/source/excited_states.rst

@@ -9,12 +9,12 @@ CIS constructs excited states by promoting electrons from occupied to virtual or
 
 RPA includes both excitation and de-excitation operators, and accounts for more electronic correlation than CIS. 
 
-Both methods are calculated with `Electronic_Structure` driver; you simply add an `excited_states` key to your `seqm_parameters` dictionary.
+Both methods are calculated with `Electronic_Structure` driver.
 
 Configuring Excited States
 --------------------------
 
-In order to prompt an excited state calculation, add an `excited_states` dictionary to `seqm_parameters`:
+In order to prompt an excited state calculation, simply add an `excited_states` key/value pair to your `seqm_parameters` dictionary:
 
 .. code-block:: python
 
@@ -34,12 +34,12 @@ This value dictionary should contain the following key/value pairs:
 
 - **method**  (`str`): Method used for excited state calculations. Available options:
 
-        - `'rpa'`
-        - `'cis'`
+  - ``'rpa'``
+  - ``'cis'``
 
-By default it is set to `cis`
+By default it is set to ``'cis'``
 
-- **cis_tolerance** (`float`): Convergence criterion for CIS/RPA excited states. By default it is set to 1e-6.
+- **cis_tolerance** (`float`): Convergence criterion for CIS/RPA excited states. By default it is set to ``1e-6``.
 
 See :ref:`seqm-parameters` for other settings for the calculation.
 
@@ -58,7 +58,7 @@ Running an Excited-State Calculation
    device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
 
    species = torch.as_tensor([[8,6,1,1],
-                              [8,6,1,1],
+                              [8,6,1,1],],
                            dtype=torch.int64, device=device)
 
    coordinates = torch.tensor([
@@ -76,27 +76,24 @@ Running an Excited-State Calculation
                                  ],
                               ], device=device)
 
-   species = torch.as_tensor(species, dtype=torch.int64, device=device)[:]
-   coordinates = torch.tensor(coordinates, device=device)[:]
    const = Constants().to(device)
 
    seqm_parameters = {
       'method': 'AM1',
       'scf_eps': 1.0e-8,
-      'scf_converger': [2],
-      'excited_states': {'n_states': 5},
+      'scf_converger': [1],
+      'excited_states': {'n_states': 10},
    }
 
    molecule = Molecule(const, seqm_parameters, coordinates, species).to(device)
    esdriver = Electronic_Structure(seqm_parameters).to(device)
    esdriver(molecule)
 
-After ``esdriver(molecule)``, inspect the ``molecule`` attributes:
+After ``esdriver(molecule)`` has run, inspect the ``molecule`` attributes:
 
-- **Excited-State Energies** (`molecule.cis_energies`)  
-  Tensor of shape `(batch, n_states)` giving excitation energies (eV) above the ground state.
+- ``molecule.cis_energies`` Tensor of shape `(batch, n_states)` containing excitation energies (eV) above the ground state.
 
-In addition, excitation energies and a few other useful quantities are printed to console.
+In addition, excitation energies and a few other useful quantities (transition dipole moments, oscillator strengths) are printed to console.
 
 Batch Homogeneity Requirement
 -----------------------------

docs/source/geometry_optimization.rst

@@ -5,10 +5,10 @@ Overview
 --------
 PYSEQM provides two approaches for finding minimum-energy structures:
 
-- **geomeTRIC** integration via `geomeTRIC_optimization`  
+- **geomeTRIC** integration 
 
-  Robust, advanced algorithms (`external package <https://geometric.readthedocs.io/en/latest/>`_; single-molecule only).
-- **Steepest-Descent (SD)** via `Geometry_Optimization_SD`  
+  Robust, advanced algorithms using an external package called `geomeTRIC <https://geometric.readthedocs.io/en/latest/>`_; single-molecule only.
+- **Steepest-Descent (SD)** via `Geometry_Optimization_SD` driver  
 
   Batch-capable but may converge extremely slowly or fail on complex surfaces.  
 
@@ -40,7 +40,6 @@ Example optimization with geomeTRIC
     import torch
     from seqm.seqm_functions.constants import Constants
     from seqm.Molecule import Molecule
-    from seqm.ElectronicStructure import Electronic_Structure
     from seqm.geometryOptimization import geomeTRIC_optimization
     
     torch.set_default_dtype(torch.float64)
@@ -75,13 +74,14 @@ Example optimization with geomeTRIC
                        }
     
     molecules = Molecule(const, seqm_parameters, coordinates, species).to(device)
+
     geomeTRIC_optimization(molecules)
 
 
 
 Built-in Steepest-Descent
 -------------------------
-Use `Geometry_Optimization_SD` for simple, batched optimization:
+Use `Geometry_Optimization_SD` driver for simple, batched optimizations:
 
 .. code-block:: python
 

docs/source/index.rst

@@ -7,7 +7,7 @@ PYSEQM (PYtorch based SemiEmpirical Quantum Mechanics) is is a flexible, high-pe
 - **Semiempirical quantum chemical calculations**  
 
   Fast evaluation of molecular energies and forces using established semiempirical methods such as AM1, PM3, PM6.
-- **GPU accelerate calculations**  
+- **GPU accelerated calculations**  
 
   Leverage NVIDIA CUDA hardware for highly accelerated simulations; also fully supported on CPU-only systems.
 - **Machine-learning integration**  

docs/source/quick_start.rst

@@ -48,12 +48,12 @@ Create a file called `run_quickstart.py` with the following contents:
 
    # 4. Run single‐point SCF
    driver = Electronic_Structure(seqm_parameters).to(device)
-   driver.(molecule)
+   driver(molecule)
 
    # 5. Print results
    print(f"Total Energy (eV):   {molecule.Etot.item():.6f}")
    print(f"Heat of Formation:   {molecule.Hf.item():.6f}")
-   print(f"Force on Atoms:\n      {molecule.force}")
+   print(f"Force on Atoms:\n{molecule.force}")
 
 3. Execute the Script
 ---------------------