Metadata-Version: 2.1
Name: clims
Version: 0.5.0
Summary: Command-Line Interface for Materials Simulations
Home-page: https://gitlab.com/FHI-aims-club/utilities/clims
Author: FHI-aims developers
License: LGPLv2.1+
Classifier: License :: OSI Approved :: GNU Lesser General Public License v2 or later (LGPLv2+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ase<3.23,>=3.21.1
Requires-Dist: spglib>=2.5.0
Requires-Dist: phonopy>=2.9.3
Requires-Dist: matplotlib>=3.4.1
Requires-Dist: click>=7.1.2
Requires-Dist: pytest>=6.2.3
Requires-Dist: numpy<2.0

# Table of Contents
[[_TOC_]]

# clims

Command-line interface for materials simulations. 

Basically pulls together usefull python packages of the materials simulation community:

* [ASE](https://wiki.fysik.dtu.dk/ase/index.html)
* [spglib](https://spglib.github.io/spglib/) (cyrstal symmetry properties)
* [phonopy](https://phonopy.github.io/phonopy/) (phonon properties from finite-differences)

This package is tailored for the needs of FHI-aims.

## System requirements

A python 3 installation with a version `python>=3.9` is required. To check your python version type:
```
python --version
```

In the following instructions on some systems it may be needed to use `python3` and `pip3`.

On a computer with such an installation, the below commands will install a number of other useful community packages for atomistic simulations as prerequisites, most importantly, `ASE`, `spglib`, `phonopy`, as well as several others.

Please also see the troubleshooting notes below in case you encounter a particular, missing prerequisite during the installation process.

## How to install

It is best to install `clims` in a virtual environment. May not always true, e.g. on computing clusters. 

### Install/Activate virtualenv (optional)

Make sure that `virtualenv` is installed:
```
pip show virtualenv 
```
If not installed, install it:
```
pip install --user virtualenv
```

Go into the root directory of clims. Initialize the virtual environment:
```
python -m venv env
```

Activate the virtual environment:
```
source env/bin/activate
```

You should now see `(env)` in at the beginning of your command line.


### Install clims

Install clims (make sure that you are in the root director of clims (where this README is)) with:
```
pip install --user .

```

If all goes well, you will have a working clims installation after this step. If something does not work (for instance, if a particular installation prerequisite that should be part of python is missing), unfortunately the error messages written by `pip` can be somewhat cryptic. As an approximate rule, the final line of a python error message often identifies the piece that was missing.

To test your installation you can run:
```
pytest -vv
```

### Troubleshooting

**Installation under CentOS**: In order for this installation to work, we noticed that the `_ctypes` module is required. This only works if the library `libffi` (including development headers - sometimes called `libffi-dev` or `libffi-devel`) is also required and the computer's python version must have been built with support for `libffi-dev` (or `libffi-devel`). If support for `libffi` headers is not present, then someone will unfortunately have to rebuild and reinstall the python >= 3.7 installation on the computer you are using from scratch.


## How to configure clims

The most important thing to set is the path to the FHI-aims species defaults:
```
clims-configure --species-path <your/path/to/FHIaims/species_defaults>
```

## Features

After successful installation the following commands should be available in the terminal:

| clims command | description |
| ------ | ------ |
| `clims-unit-cell-info` | Get brief overview of input structure, if periodic: generate primitive or conventional unit cell. |
| `clims-supercell` | Generate a supercell. |
| `clims-convert`| Convert input files formats and convert atomic coordinates of a periodic structure from Cartesian to real and vice versa. |
| `clims-phonopy` | Generate supercell structures with displaced atoms (initialize) and read forces after FHI-aims calculation to plot phonon DOS (postprocess). |
| `clims-wigner-seitz-cluster` | Constructs a atom-cluster of the shape of the Wigner-Seitz cell. |
| `clims-aimsplot` | Tool for plotting band structure and DOS from FHI-aims. |
| `clims-xyplot` | Simple X-Y plot of data files. |
| `clims-prepare-run` | Create `control.in` template based on a `geometry.in` file. If requested, a submission file is provided, too. |
| `clims-configure` | Configure Path to exectutable and species defaults directory, mpi run command, submission header. Needed e.g. for `clims-prepare-run` |
| `clims-testsuite` | Create a testsuite of all defined input parameter combinations. |
