orb-analysis 0.1.2
the package can be used for analysing fragment calculations with the AMS software package
License: MIT

# Orb_analysis

[![Testing](https://github.com/SiebeLeDe/orbitals/actions/workflows/build_python_versions.yml/badge.svg)](https://github.com/SiebeLeDe/orbitals/actions/workflows/build_python_versions.yml.yml)

<!-- [![Documentation](https://github.com/SiebeLeDe/orbitals/actions/workflows/build_docs.yml/badge.svg)](https://github.com/SiebeLeDe/orbitals/actions/workflows/build_docs.yml) -->

[![PyPI version](https://badge.fury.io/py/orb-analysis.svg)](https://badge.fury.io/py/orb-analysis) [![PyPI pyversions](https://img.shields.io/pypi/pyversions/orb-analysis.svg)](https://pypi.python.org/pypi/orb-analysis/) [![PyPI license](https://img.shields.io/pypi/l/orb-analysis.svg)](https://pypi.python.org/pypi/orb-analysis/) [![PyPI status](https://img.shields.io/pypi/status/orb-analysis.svg)](https://pypi.python.org/pypi/orb-analysis/)

![Overview Figure](docs/_static/Overview_figure.png)

## Introduction

Analyzing molecular orbital (MO) diagrams and plotting these orbitals can be a tedious task and may require many hours spent replotting orbitals to your liking. For example, you first have to find relevant symmetrized fragment orbitals (SFOs) that form MOs. Often certain data is crucial such as the orbital energy, gross populations and HOMO/LUMO (highest occupied molecular orbital / lowest unoccupied molecular orbital) indices. Consequentially, the user needs to make pictures of the SFOs / MOs, apply the correct energy scaling, and finalize MO diagrams. This can be made much more efficient by having a python interface to automate analysis and visualization, making it much more enjoyable and clearer to analyze the results of your calculations.

## Purpose

The purpose of this package is to provide a python interface to analyze fragment calculations that can be performed using the [AMS](https://www.scm.com/doc/AMS/index.html) / [ADF](https://www.scm.com/doc/ADF/index.html) engine. This package may also be useful for other type of calculations, but is not guaranteed to work. The package is written in python and uses the [plams](https://www.scm.com/doc/plams/index.html) package to interface with the AMS software. The package is tested with AMS2023.104.

## Installation

There are several ways to install the python package:

- [X] Locally: first clone the github page and move to the directory. Then install it locally in your python environment with
  ``pip install -e .``
- [X] PyPI: ``pip install orb_analysis``

The required python environment is taken care of by the package manager. Note that you should have a working python environment with the required dependencies installed. See the [setup configuration file](setup.cfg) for a list of dependencies. I recommend using [conda](https://docs.conda.io/en/latest/) to manage your python environment with python version 3.10 or higher.

Furthermore, please make sure that you have the AMS software installed and that the amsview and amsreport programs are available in your path. The package is tested with AMS2023.204.

## Example

Tutorials covering key functionality can be found in the [example folder](scripts). Several scripts are available to show how the package works. The rkf files used in the examples can be downloaded from [here](test/fixtures/rkfs/).

1. The [first script](scripts/densf_example.py) illustrates how to obtain volume files from .t21 result files from the AMS ADF engine. The .adf.rkf are read in, and the voluma maps are generated by a plams.DensfJob implementation. Presets are made for easy-accessible settings.
2. The [second script](scripts/analysis_example.py) illustrates how to analyze fragment calculations consisting of multiple fragments and a complex. The script will ask for the location of the .adf.rkf file, and ask for the desired MOs to plot with the desired irrep and spin. The script will then generate a table with the symmetrized fragment orbitals (SFOs), SFO overlap matrix, and the molecular orbitals (MOs)
3. When installing the package using PyPI, the [third script](scripts/plot_example.py) illustrates how to use the package from the command line. The script can be run from the command line with ``orb_analysis`` and associated arguments. The script will ask for the location of the .adf.rkf file, and ask for the desired MOs to plot with the desired irrep and spin. The script will then generate a table with the symmetrized fragment orbitals (SFOs), SFO overlap matrix, and the molecular orbitals (MOs)

## Extent of the package

The package is currently in development and is not yet fully functional. The following functionality is currently available:

- [X] Reading in .adf.rkf files and selecting orbitals based on homo/lumo range, irrep, and spin.
- [X] Obtaining SFOs from all fragments
- [X] Obtaining SFO overlap matrix
- [X] Obtaining MOs from the complex
- [X] Format SFOs, the and MOs in a table

For the following types of fragment analysis calculations:

- [X] Unrestricted and restriced
- [X] Frozen cores ranging from "none" to "large"
- [X] Fragments with the same symmetry as the complex
- [X] Fragments with symmetry, complex without symmetry
- [X] Neither fragments nor complex with symmetry
- [X] With and without relativistic corrections (only tested for scalar ZORA and no corrections)

The following functionality is currently not available:

- [X] Fragments with different symmetry as the complex

- [...] (more to come)

## Docs

Not yet available.

## Authors

Siebe Lekanne Deprez, PhD student at the Vrije Universiteit Amsterdam (VU) working in the theoretical chemistry department.

## License

This package is licensed under the [MIT License](LICENSE.txt).

## How to cite

Lekanne Deprez, S.J., orb_analysis, 2023, <https://github.com/SiebeLeDe/orbitals>

## How to contribute

Everyone is welcome to contribute to this project. Please do so by making a pull request and/or raising an issue. Preferably, please use the Google Python Style Guide and the Google docstring style when writing code (including docstrings!).

## Dependencies

Please visit the [requirements file](requirements.txt) for a list of dependencies. The whole package is written in a python environment and is compatible for python versions 3.10 and higher.

## Contact Me

If you wish to contact me, please do so by sending an email to [my mail adres](s.j.lekanne.deprez@vu.nl), or by raising an issue on GitHub.

## FAQ

Let me know if there are questions so that I could include this further!