Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mineralscloud/qha

A Python package for calculating thermodynamic properties under quasi-harmonic approximation, using data from ab-initio calculations
https://github.com/mineralscloud/qha

ab-initio phonon python3 quasi-harmonic-approximation scientific-computing thermodynamic-properties

Last synced: 19 days ago
JSON representation

A Python package for calculating thermodynamic properties under quasi-harmonic approximation, using data from ab-initio calculations

Host: GitHub
URL: https://github.com/mineralscloud/qha
Owner: MineralsCloud
License: gpl-3.0
Created: 2018-04-25T00:07:27.000Z (over 6 years ago)
Default Branch: master
Last Pushed: 2024-02-18T01:15:26.000Z (10 months ago)
Last Synced: 2024-11-29T15:34:03.859Z (23 days ago)
Topics: ab-initio, phonon, python3, quasi-harmonic-approximation, scientific-computing, thermodynamic-properties
Language: Python
Homepage: https://mineralscloud.github.io/qha/
Size: 3.04 MB
Stars: 27
Watchers: 4
Forks: 14
Open Issues: 8
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Citation: CITATIONS.bib

Awesome Lists containing this project

README

# qha: A Powerful Python toolkit for quasi-harmonic approximation

[TOC]

[![Stable docs](https://img.shields.io/badge/docs-stable-blue.svg)](https://mineralscloud.github.io/qha/)
[![Build Status](https://travis-ci.com/MineralsCloud/qha.svg?branch=master)](https://travis-ci.com/MineralsCloud/qha)

| category | percent | downloads |
| --------------- | ------- | --------- |
| with_mirrors | 100.00% | 2,801 |
| without_mirrors | 20.67% | 579 |
| Total | | 2,801 |

Date range: 2023-04-20 - 2023-10-17

## Contributors

This repository is now maintained by [Qi Zhang](mailto:[email protected]). Thanks to the contribution from [Chenxing Luo](https://github.com/chazeon).

## How to cite

The associated paper is published on [Computer Physics Communications](https://www.sciencedirect.com/science/article/pii/S0010465518303953?via%3Dihub).

Please cite this article as: T. Qin, Q. Zhang, R.M. Wentzcovitch et al., qha: A Python package for quasiharmonic free energy calculation for multi-configuration systems, Computer Physics Communications (2018), https://doi.org/10.1016/j.cpc.2018.11.003.

## Quick start: installation

### Python environment

`qha` is written in Python, and can be installed from [Python package index (PyPI)](https://pypi.org/search/?q=qha) or local source files.

Python 3 can be downloaded from its official [website](https://www.python.org/) for systems including Windows, macOS, and Linux,
please check more details on [Python 3 documentation](https://docs.python.org/3/using/index.html).

To install `qha`, currently, Python 3.6.x distributions are recommended.

### Where to get it

Binary installers for the latest released version are available at the PyPI.

```shell
# use PyPI
$ pip install qha
```

### Dependencies

- [mpmath](https://mpmath.org/)
- [lazy-property](https://github.com/jackmaney/lazy-property)
- [matplotlib](https://matplotlib.org)
- [Numba](http://numba.pydata.org)
- [NumPy](http://www.numpy.org)
- [pandas](https://pandas.pydata.org)
- [PyYAML](http://pyyaml.org)
- [scientific-string](https://github.com/singularitti/scientific-string)
- [SciPy](https://www.scipy.org)
- [text-stream](https://github.com/singularitti/text-stream)

### Installation from sources

The source code is currently hosted on [GitHub](https://github.com/MineralsCloud/qha). Please go to [the “releases” page](https://github.com/MineralsCloud/qha/releases) to download the tagged releases. Unzip the downloaded sources, go to the top-level directory (e.g., `/path/to/repo/qha`), run

```shell
$ pip install .
```

Notice that you have to use Python version > 3.6.x to install. If you want to install `qha` in development mode, instead run

```shell
$ pip install -e .
```

## Checking the examples

To run the examples, go to `examples/ice VII/` or `examples/silicon/` directories and type in terminal:

```shell
$ qha run /path/to/settings.yaml
```

If you want to plot your results, in the same folder, run

```shell
$ qha plot /path/to/settings.yaml
```

## Structure of the `qha` package

The `qha` source code consists of three major parts.

1. `./qha` directory contains all the source code.

2. `./examples` directory contains two examples, `./examples/silicon` is the example for single-configuration calculation, `./examples/ice VII` is the example for multi-configuration calculation.

The brief of the organization of these directories follows as below:

### The main folder `./`

This main folder contains three folders, license file, readme file, and setup file.

`LICENSE.txt`: The license file attached with the `qha` code;

`README.md`: Readme file of the code, it would be better to view it in a [Markdown](https://en.wikipedia.org/wiki/Markdown) editor, e.g., [Typora](https://typora.io);

`setup.py`: setup file needed for installation of the `qha` Python package.

#### The `./qha/` folder

`qha/__init__.py`: Tells Python interpreter that this is a Python package;

`qha/calculator.py`: Perform single-, multi-configuration calculations, one of the most crucial modules in this code;

`qha/fitting.py`: Perform the Birch—Murnaghan (BM) equation-of-state (EOS) fitting;

`qha/grid_interpolation.py`: Find the most suitable volume grid to perform the BM EOS fitting;

`qha/plotting.py`: A simple module to plot the calculated physical properties;

`qha/settings.py`: Define some computational settings for the calculation;

`qha/single_configuration.py`: Calculate the Helmholtz free energy for a single-configuration system;

`qha/statmech.py`: Define some useful statistical mechanics functions;

`qha/thermodynamics.py`: Derive the internal energy($U$), enthalpy($H$), and Gibbs free energy ($G$) from the calculated Helmholtz free energy ($F$) via basic thermodynamics relationship;

`qha/tools.py`: Define some miscellaneous functions used in the code, e.g., function used to perform Lagrange interpolation;

`qha/type_aliases.py`: Define some types for annotation in the code;

`qha/unit_conversion.py`: A module to convert units used in the calculation;

`qha/v2p.py`: Contain the function `v2p` used to convert calculated properties on $(T, V)$ grid to $(T, P)$ grid;

`qha/input_maker.py`: Generate the input file for `qha` from results obtained from _ab initio_ calculation;

`qha/out.py`: Functions used to write calculated properties into files.

##### The `./qha/readers` folder

`qha/readers/__init__.py`

`qha/readers/read_input.py`: This module is used to read the input file.

##### The `./qha/cli` folder

This folder contains files used for the command-line interface.

`qha/cli/__init__.py`

`qha/cli/converter.py`

`qha/cli/handler.py`

`qha/cli/parser.py`

`qha/cli/plotter.py`

`qha/cli/runner.py`

##### The `./qha/multi_configurations` folder

This folder contains files to calculate Helmholtz free energy for the multi-configuration system.

`qha/multi_configurations/__init__.py`

`qha/multi_configurations/different_phonon_dos.py`: Work with `qha/calculator.py` to calculate Helmholtz free energy for the multi-configuration system with different phonon density of states (VDOS) for each configuration;

`qha/multi_configurations/same_phonon_dos.py`: Work with `qha/calculator.py` to calculate Helmholtz free energy for multi-configuration system with the same VDOS for all configurations.

##### The `./qha/tests` folder

this folder contains unit test files

`qha/tests/__init__.py`

`qha/tests/test_overall_run.py`

`qha/tests/test_read_input.py`

`qha/tests/test_samevdos_overall.py`

`qha/tests/test_single_configuration.py`

`qha/tests/test_unit_conversion.py`

#### The `./examples/` folder

This folder contains two examples for demonstration purpose.

##### The `./examples/silicon` folder

This folder conations an example to perform the single-configuration calculation. Also, an example to generate the input file for the `qha` code is included, check `examples/silicon/make_input/README` for details;

`examples/silicon/input`: The input file for `qha`;

`examples/silicon/settings.yaml`: This file is the computational settings file.

##### The `./examples/ice VII` folder

`examples/ice VII/input_01` : `input_01` through `input_52` are the input files of 52 distinguish configurations;
`examples/ice VII/input_02`
`examples/ice VII/input_03`
`…`
`examples/ice VII/input_52`

`examples/ice VII/settings.yaml`: This file is the computational settings file, see our online [tutorial](https://mineralscloud.github.io/qha/tutorials/index.html) for more details.

## License

[GNU General Public License v3](./LICENSE.txt)

## Documentation

The official documentation is hosted on our [GitHub page](https://mineralscloud.github.io/qha/).

## Stargazers over time

[![Stargazers over time](https://starchart.cc/MineralsCloud/qha.svg?variant=adaptive)](https://starchart.cc/MineralsCloud/qha)