Metadata-Version: 2.4
Name: cogito-dft
Version: 0.1.0
Summary: Crystal Orbital Guided Iteration To atomic-Orbitals (COGITO) finds an adaptive atomic orbital basis for a given density functional theory (DFT) run, and then decodes the atom and bond contributions to electronic structure.
Requires-Python: >=3.4
Description-Content-Type: text/markdown
Requires-Dist: numpy>=2.0.0
Requires-Dist: scipy>=1.15.0
Requires-Dist: matplotlib
Requires-Dist: plotly
Requires-Dist: pymatgen
Requires-Dist: seekpath==2.1.0
Provides-Extra: plot
Requires-Dist: scikit-image; extra == "plot"
Requires-Dist: dash; extra == "plot"
Requires-Dist: dash-ag-grid; extra == "plot"

# COGITO - Crystal Orbital Guided Iteration To atomic-Orbitals

[![Website](https://img.shields.io/badge/website-live-green?style=flat-square)](https://cogito-dft.readthedocs.io/)
[![COGITO](https://img.shields.io/badge/main%20repo-COGITO-blue?style=flat-square)](https://github.com/olipemil/COGITO-dft)

This repository hosts the code for COGITO, a tool for obtaining quantum chemistry from plane wave DFT calculations. The main codes modules are COGITO, COGITOpost, COGITOanalyze, and COGITOico.

## Installation

```bash
pip install --upgrade pip
pip install cogito-dft
```

To install optional dependences (scikit-image, dash, dash-ag-grid) that are used in some COGITOpost functions:

```bash
pip install "cogito-dft[plot]"
```

To avoid thread oversubscription and possible stalls **(especially on HPC)**, set:

```bash
export OMP_NUM_THREADS=1
```

## Quick Start

**Visit the live website:** [**cogito-dft.readthedocs.io**](https://cogito-dft.readthedocs.io/)

| Section | Description |
|---------|-------------|
| [Tutorial](https://cogito-dft.readthedocs.io/en/latest/tutorial.html) | Step-by-step analysis workflow |
| [File Guide](https://cogito-dft.readthedocs.io/en/latest/file_struc.html) | Interactive guide of inputs and outputs |
| [API Docs](https://cogito-dft.readthedocs.io/en/latest/api_ref.html) | Complete function reference |

**Basic Workflow:**

1. **Run VASP** - Static calculation with saved wavefunctions and high NBANDS
2. **Generate COGITO model** - Creates COGITO basis functions and tight binding parameters
3. **Verify quality** - Check convergence, charge spilling, orbital mixing, and band interpolation
4. **Analyze chemistry** - COHP, bonding, charge analysis

```bash
# Run VASP 
vasp_std

# See 'COGITO --help' for variable options
COGITO --dir './'

# Check that quality metrics are within range (check band interpolation after COGITOpost)
COGITOanalyze --dir './'

# Generate atom and bond partition of charge / band energies, make bond plots, and more
COGITOpost --dir './'
# Customize a runTBmodel.py file to get specific plots
python runTBmodel.py
```

