Improve README and externalize DFTB parameters

README.md

@@ -3,40 +3,101 @@
 
 # ThermoScreening
 
-## Description
+ThermoScreening calculates thermochemical properties for molecular systems and provides a foundation for screening molecule sets. It currently supports thermochemistry workflows from DFTB+ inputs and exposes Python APIs for reading coordinates, parsing vibrational data, and running thermodynamic post-processing.
 
-ThermoScreening is a program to calculate the thermochemical properties of given molecules. The aim is to create a framework to allow screening databases of molecules for their thermochemical properties.
+## Features
 
-## License
+- Thermochemistry calculations for molecular systems
+- DFTB+ geometry optimization, Hessian, and normal-mode integration
+- Readers for DFTB+ `.gen`, XYZ, and vibrational frequency files
+- Runtime type checking for public API calls
+- Test coverage for parsing, thermochemistry, and optional DFTB+ execution paths
 
-ThermoScreening source code is licensed under the GNU Lesser General Public License v2.1 or later. See [LICENSE](LICENSE). Bundled third-party data remains under the license files in `external/`.
+## Installation
 
-## Development Guide
+Install the package from a checkout:
 
-1. Clone the repository
 ```bash
-git clone https://github.com/MolarVerse/ThermoScreening.git
+python -m pip install .
 ```
-2. Use git flow
+
+For development and tests:
+
 ```bash
-[master] main
-[develop] dev
-[version tag prefix] v
+python -m pip install -e ".[test,lint]"
 ```
-3. Create a feature branch
+
+## DFTB+ Setup
+
+DFTB+ calculations require two external pieces:
+
+1. The `dftb+` and `modes` executables on `PATH`.
+2. Slater-Koster parameter files downloaded separately from DFTB.org.
+
+ThermoScreening does not vendor Slater-Koster files. Point the calculator to a parameter directory in one of two ways:
+
 ```bash
-git flow feature start <feature_branch>
+export DFTB_PREFIX=/path/to/3ob-3-1/
+```
+
+or pass `slako_dir` explicitly:
+
+```python
+from ThermoScreening.thermo.api import dftbplus_thermo
+
+thermo = dftbplus_thermo(
+    atoms,
+    slako_dir="/path/to/3ob-3-1/",
+)
 ```
-5. Commit your changes to the feature branch
+
+The bundled DFTB+ parameters were removed from the repository because they are large, independently licensed scientific data. Keeping them external makes the package smaller and keeps parameter-set licensing explicit.
+
+## Usage
+
+Run thermochemistry from an input file with the command-line entry point:
+
 ```bash
-git add <files>
-git commit -m "message"
-git flow feature publish <feature_branch>
+thermo path/to/thermo.in
 ```
 
-## TODO
-- [ ] Add different engine
-- [ ] Add conformer generator
-- [ ] Add more tests
-- [ ] Add a documentation
-- [ ] Add screening framework
+Use the Python API when integrating ThermoScreening into another workflow:
+
+```python
+from ThermoScreening.thermo.api import run_thermo
+
+thermo = run_thermo(
+    vibrational_frequencies,
+    coord_file="geo_opt.xyz",
+    temperature=298.15,
+    pressure=101325,
+    energy=electronic_energy,
+    engine="dftb+",
+)
+
+print(thermo.total_gibbs_free_energy())
+```
+
+## Testing
+
+Run the full test suite:
+
+```bash
+python -m pytest -q
+```
+
+Run linting:
+
+```bash
+python -m pylint ThermoScreening
+```
+
+DFTB+ integration tests run only when the executables are available and `DFTB_PREFIX` points to a valid Slater-Koster directory. Otherwise they are skipped so the pure-Python test suite remains portable.
+
+## Roadmap
+
+Planned work is tracked in GitHub issues rather than in this README. Current roadmap areas include additional engines, conformer generation, broader test coverage, documentation, and batch screening workflows.
+
+## License
+
+ThermoScreening source code is licensed under the GNU Lesser General Public License v2.1 or later. See [LICENSE](LICENSE).

ThermoScreening/calculator/dftbplus.py

@@ -6,16 +6,25 @@
 import numpy as np
 
 from ..utils.physicalConstants import PhysicalConstants
-from ThermoScreening import BASE_PATH
 
 # --------------------------------------------------------------------------- #
 
 
-DEFAULT_SLAKO_DIR = BASE_PATH + "../external/slakos/3ob-3-1/"
+def _slako_dir(slako_dir=None):
+    selected_dir = slako_dir or os.getenv("DFTB_PREFIX")
+    if not selected_dir:
+        raise FileNotFoundError(
+            "Slater-Koster files are not bundled with ThermoScreening. "
+            "Set DFTB_PREFIX or pass slako_dir to the DFTB+ calculator."
+        )
 
+    selected_dir = os.path.abspath(os.path.expanduser(selected_dir))
+    if not os.path.isdir(selected_dir):
+        raise FileNotFoundError(
+            f"Slater-Koster directory does not exist: {selected_dir}"
+        )
 
-def _slako_dir(slako_dir=None):
-    return slako_dir or os.getenv("DFTB_PREFIX") or DEFAULT_SLAKO_DIR
+    return selected_dir + os.sep
 
 
 class Geoopt(Dftb):
@@ -66,7 +75,7 @@ def __init__(
             Charge of the system. Default is 0.
         slako_dir : str
             Path to the Slater-Koster files. If None, it will look
-            for the DFTB_PREFIX environment variable. Default is 3ob-3-1.
+            for the DFTB_PREFIX environment variable.
         max_force : float
             Maximum force component. Default is 1.0e-6.
 
@@ -170,7 +179,7 @@ def __init__(
             Finite difference step. Default is 1.0e-4.
         slako_dir : str
             Path to the Slater-Koster files. If None, it will look
-            for the DFTB_PREFIX environment variable. Default is 3ob-3-1.
+            for the DFTB_PREFIX environment variable.
 
         Other Parameters:
         -----------------

ThermoScreening/thermo/api.py

@@ -515,7 +515,6 @@ def dftbplus_thermo(
     modes = Modes()
     frequencies = modes.wave_numbers
 
-    # TODO: rewrite run_thermo function to include ase atoms object
     # run thermo calculation
     thermo = run_thermo(
         frequencies,

ThermoScreening/thermo/thermo.py

@@ -191,9 +191,6 @@ def _relocate_to_cm(self):
         None
         """
 
-        # ? Resolving the issue with the center of mass calculation
-        # TODO: check if coord is correct because it is not returning the relocate coordinates
-        # DONE: solved the issue with the center of mass calculation
         self._reloc_coord = self._system.coord()
         self._reloc_coord -= self._system.center_of_mass
 
@@ -207,8 +204,6 @@ def _compute_inertia_tensor(self):
         -------
         None
         """
-        # TODO: coord is not relocated to the center of mass
-        # DONE: solved the issue with the center of mass calculation
         coord = self._reloc_coord
         x = coord[:, 0]
         y = coord[:, 1]
@@ -239,7 +234,6 @@ def _compute_rotational_partition_function(self):
         None
         """
 
-        # TODO: resolve with naming pylint issue 
         self._eigenvalues_I_SI = (
             self._eigenvalues_I * PhysicalConstants["u"] * PhysicalConstants["A"] ** 2
         )