Metadata-Version: 2.2
Name: cp2k-spm-tools
Version: 1.4.4
Summary: CP2K Scanning Probe Microscopy tools.
Author-email: Kristjan Eimre <kristjaneimre@gmail.com>, Edoardo Baldi <edoardo.baldi@empa.ch>
License: MIT License
        
        Copyright (c) 2019 Kristjan Eimre
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/nanotech-empa/cp2k-spm-tools
Project-URL: Bug Tracker, https://github.com/nanotech-empa/cp2k-spm-tools/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2,>=1.22
Requires-Dist: scipy<2,>=1.10
Requires-Dist: ase<4,>=3.15
Requires-Dist: matplotlib<4,>=3.0
Requires-Dist: mpi4py>3.1
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"

[![DOI](https://zenodo.org/badge/133041124.svg)](https://zenodo.org/badge/latestdoi/133041124)

## CP2K Scanning Probe Microscopy tools

Library and scripts to perform scanning probe microscopy simulations based on a [CP2K](https://www.cp2k.org/) calculation.

Features include:

- Processing the various output files of [CP2K](https://www.cp2k.org/), including the `.wfn` file
- Scanning Tunnelling Microscopy and Spectroscopy (STM/STS) analysis
- Fourier-Transformed STS analysis for finite cutouts of periodic systems
- Orbital hybridization analysis for adsorbed systems
- High-resolution STM (HRSTM) simulations

### Installation

The package requires an MPI implementation to be available on your system for `mpi4py`. You can install it:

- On Linux: through your package manager (e.g., `apt install mpich` or `yum install mpich`)
- On macOS: through Homebrew (`brew install mpich`)
- On Windows: through conda (`conda install -c conda-forge mpich`)

Then install the package with pip:
```bash
pip install cp2k-spm-tools
```

Or, for development:
```bash
git clone https://github.com/nanotech-empa/cp2k-spm-tools.git
cd cp2k-spm-tools
pip install -e .[dev]
```

### Command Line Tools

The package provides several command-line tools, including:

- `cp2k-stm-sts-wfn`: STM/STS analysis from wavefunction files
- `cp2k-cube-from-wfn`: Create cube files from wavefunction files
- `cp2k-bader-bond-order`: Bond order analysis based on Bader basins

Use `--help` with each command to see its options.

### Example Usage

When everything is set up correctly, the bash scripts in `examples/` folder can be executed without any further input and illustrate the usage of the various scripts. For example `example/benzene_stm/run_stm_sts_from_wfn.sh` evaluates the STM/STS signatures of isolated benzene at each orbital energy (`out/orb/`) as well as in an arbitrary energy range (`out/stm/`). The corresponding CP2K calculation is included in the repository.

**NB: In all cases, the underlying DFT calculation has to be performed with the diagonalization algorithm rather than orbital transformation (OT).**

### Python API Example

Most of the functionality of this library is built on top of the possibility to evaluate the Kohn-Sham orbitals encoded in the `.wfn` file on an arbitrarily defined grid. This is illustrated by the following script applied for a nanographene adsorbed on a Au(111) slab (total of 1252 atoms and 10512 electrons):

```python
from cp2k_spm_tools.cp2k_grid_orbitals import Cp2kGridOrbitals

### Create the gridding object and load the cp2k data ###
cgo = Cp2kGridOrbitals()
cgo.read_cp2k_input("./cp2k.inp")
cgo.read_xyz("./geom.xyz")
cgo.read_basis_functions("./BASIS_MOLOPT")
cgo.load_restart_wfn_file("./PROJ-RESTART.wfn", n_occ=2, n_virt=2)

### Evaluate the orbitals in the specific region ###
cgo.calc_morbs_in_region(
    dr_guess = 0.15,                          # grid spacing
    x_eval_region = None,                     # take whole cell in x
    y_eval_region = [0.0, cgo.cell_ang[1]/2], # half cell in y
    z_eval_region = [19.0, 24.0],             # around the molecule in z
)

cgo.write_cube("./homo.cube", orbital_nr=0)
```
