{ "cells": [ { "cell_type": "markdown", "metadata": { "collapsed": false, "pycharm": { "name": "#%% md\n" } }, "source": [ "### Introduction\n", "\n", "κALDo is a versatile and scalable open-source software to compute phonon transport in crystalline and amorphous solids. It features real space QHGK calculations and three different solvers of the linearized BTE: direct inversion, self-consistent cycle, and RTA. \n", "\n", "The algorithms are implemented using linear algebra operations on tensors, to take advantage of multithreading on GPU and CPU using Numpy, Tensorflow and optimized tensor libraries.\n", "\n", "Using the Atomic Simulation Environment, κALDo can calculate the IFCs using several ab initio and molecular dynamics codes, thus enabling the use of first-principles DFT, empirical forcefields and semi-empirical tight- binding. A native LAMMPS interface is also available in the USER-PHONON package. Finally, through seamless integration with the hiPhive package, the IFC calculation can take advantage of compressing-sensing machine learning algorithms\n", "\n", "The code is released open-source for the community to use and contribute with edits and suggestions. It is designed on modern software best practices, and we hope to provide a development platform to implement new theory and methods.\n", "\n", "\n", "### Quick Install\n", "\n", "We recommend creating a new environment with Python 3.6, 3.7, or 3.8.\n", "```bash\n", "conda create -n kaldo python=3.7\n", "```\n", "and enable the environment\n", "```bash\n", "conda activate kaldo\n", "conda install pip\n", "```\n", "\n", "kALDo installation can be done using `pip`\n", "```bash\n", "pip install git+https://github.com/nanotheorygroup/kaldo\n", "```\n", "\n", "#### Using `pip` and `virtualenv`\n", "\n", "You can also install kALDO without using `conda`\n", "```bash\n", "pip3 install virtualenv\n", "virtualenv --system-site-packages -p python3 ~/kaldo\n", "source ~/kaldo/bin/activate\n", "pip3 install git+https://github.com/nanotheorygroup/kaldo\n", "```\n", "#### Development mode\n", "\n", "The best way to run examples, tests and to develop kaldo is to follow the quick install procedure, and add the following extra steps.\n", "```bash\n", "pip uninstall kaldo\n", "make ~/develoment\n", "cd ~/development\n", "git clone git+https://github.com/nanotheorygroup/kaldo\n", "export PYTHONPATH=~/development/kaldo:$PYTHONPATH\n", "```\n", "If you followed the steps in the quickstart and then uninstall kaldo, you will have all the dependencies correctly installed.\n", "The next lines are pulling the repo from Github and adding it to the `PYTHONPATH`.\n", "\n", "If you want to make the last change in the `PYTHONPATH` permanent, you can also run\n", "```bash\n", "echo \"export PYTHONPATH=~/development/kaldo:$PYTHONPATH\" >> ~/.bashrc\n", "```\n", "\n", "\n", "\n", "### Interfacing with Other Codes\n", " \n", "#### LAMMPS library setup\n", "\n", "In order to use LAMMPS with ASE, it needs to be compiled a lib\n", "```bash\n", "cd path/to/lammps/src\n", "make yes-manybody\n", "make yes-molecule\n", "...\n", "make mpi mode=shlib\n", "```\n", "Next, activate your environment\n", "```\n", "conda activate kaldo\n", "```\n", "or if you used `virtualenv`\n", "```\n", "source ~/kaldo/bin/activate\n", "```\n", "and finally install `lammpslib` using\n", "```\n", "make install-python\n", "```\n", "Update 07/2020: It you are having any issue with the July 2020 version of `lammpslib`, try using the October 2019 version.\n", "\n", "#### LAMMPS executable setup\n", "\n", "You can use LAMMPS executable directly, as illustrated in the example folder.\n", "For that purpose, you will need the [LAMMPS user-phonon package by Charles Sievers](https://lammps.sandia.gov/doc/Packages_details.html#pkg-user-phonon) to calculate the dynamical matrix and the third order interatomic force constants.\n", "\n", "#### Quantum Espresso setup\n", "\n", "In order to use QE with ASE, Set the environment variable:\n", "```bash\n", "export ASE_ESPRESSO_COMMAND=\"mpirun -np 4 /path/to/pw.x -in PREFIX.pwi > PREFIX.pwo\"\n", "```\n", "Update 01/2021: It you are having any issue with ASE version 3.20+, try using ASE version 3.19.1.\n", "\n", "\n", "See the [ASE documentation](https://wiki.fysik.dtu.dk/ase/ase/calculators/calculators.html) for more info.\n", "\n", "### Output Storage\n", "\n", "#### Default Storage\n", "\n", "When using the storage `formatted`, kALDo stores the following dense tensor as formatted, human readable, files:\n", "\n", "- `frequency` $(n_{kpoints}, n_{modes})$. mode changes first k changes after\n", "- `velocity_alpha` $(n_{kpoints}, n_{modes})$\n", "- `physical_mode___` $(n_{kpoints}, n_{modes})$\n", "\n", "- `//heat_capacity` $(n_{kpoints}, n_{modes})$\n", "- `//population` $(n_{kpoints}, n_{modes})$\n", "\n", "- `/////conductivity__` $(n_{kpoints}, n_{modes})$ where the `/` folder is created only if those values are defined\n", "- `///diffusivity` $(n_{kpoints}, n_{modes})$\n", "- `////mean_free_path` $(n_{kpoints}, n_{modes})$\n", "- `///lifetime` $(n_{kpoints}, n_{modes})$\n", "- `///bandwidth` $(n_{kpoints}, n_{modes})$\n", "- `///phase_space` $(n_{kpoints}, n_{modes})$\n", "- `flux_dense` $(n_{kpoints}, n_{modes}, n_{kpoints}, n_{modes})$, when `diffusivity_threshold` is not specified.\n", "- `//flux_sparse` $(n_{kpoints}, n_{modes}, n_{kpoints}, n_{modes})$. Sparse only when `diffusivity_threshold` is specified.\n", "\n", "\n", "The folder structure depends on the input parameters to the Phonon Object\n", "and in parenthesis is the shape of the tensor. All of the above observables are stored in a dense format, \n", "except for `flux_alpha` which is stored as formatted file in a `index value` format.\n", "\n", "The following tensors are stored in raw binary format and help saving time when performing different simulations on the same sample.\n", "\n", "- `_eigensystem (eigenvalues and eigenvectors)`\n", "- `_dynmat_derivatives`\n", "- `///_generalized_diffusivity` \n", "- `///_ps_and_gamma_tensor`\n", "- `///_ps_and_gamma`, when only RTA conductivity is required\n", "\n", "#### Alternative Storage\n", "\n", "Other storage options available are `numpy` and `hdf5` where all the files are saved as one of those formats.\n", "Finally the `memory` option doesn't store any permanent files.\n", "\n", "| Measurement | Units |\n", "|-------------------------|--------------------------|\n", "| Distances | $A$ |\n", "| Masses | $g/N_A$ |\n", "| Frequencies | $THz$ |\n", "| Potential Derivatives | $eV/(A^2)$ or $eV/(A^3)$ |\n", "| Conductivity [$\\kappa$]| $\\frac{W}{m\\ K}$ |\n", "\n", "\n", "\n", "### Code Architecture\n", "\n", "\n", "\n", "\n", "### Main Features\n", "\n", "Below we illustrate the main features of the code\n", "\n", "\n", "\n", "### Examples\n", "\n", "Examples and the explanation on how to use them are located in the [examples folder of the repo](https://github.com/nanotheorygroup/kaldo/tree/master/examples).\n", "\n", "\n", "### How to cite\n", "\n", "If you have used kALDo, please cite the following article:\n", "\n", "Barbalinardo, G.; Chen, Z.; Lundgren, N. W.; Donadio, D. Efficient Anharmonic Lattice Dynamics Calculations of Thermal Transport in Crystalline and Disordered Solids. J Appl Phys 2020, 128 (13), 135104–135112. https://doi.org/10.1063/5.0020443\n", "also available open access on ArXiv: https://arxiv.org/abs/2009.01967\n", "\n", "```\n", "@article{kaldo,\n", "author = {Barbalinardo, Giuseppe and Chen, Zekun and Lundgren, Nicholas W and Donadio, Davide},\n", "title = {{Efficient anharmonic lattice dynamics calculations of thermal transport in crystalline and disordered solids}},\n", "journal = {Journal of Applied Physics},\n", "year = {2020},\n", "volume = {128},\n", "number = {13},\n", "pages = {135104--12},\n", "month = oct\n", "}\n", "```\n", "\n", "### Copyright\n", "\n", "Copyright (c) 2020, Giuseppe Barbalinardo, Zekun Chen, Nicholas W. Lundgren, Davide Donadio\n", "\n", "### Acknowledgements\n", "\n", "\n", "\n", "We gratefully acknowledge support by the Investment Software Fellowships (grant No. ACI-1547580-479590) of the NSF Molecular Sciences Software Institute (grant No. ACI-1547580) at Virginia Tech. \n", "\n", "MolSSI builds open source software and data which serves the computational molecular science community. [Explore MolSSI’s software infrastructure projects.](https://molssi.org/software-projects/)\n", "\n", "### Other codes\n", "\n", "We are thankful to the whole open-source community, and in particular we want to acknowledge some other great anharmonic lattice dynamics related projects. If using kALDo example, you \n", "If, while you are running kALDo examples, you use any of these codes, please don't forget to cite them. \n", "\n", "- ASE: A. H. Larsen, J. J. Mortensen, J. Blomqvist, I. E. Castelli, R. Christensen, M. Dułak, J. Friis, M. N. Groves, B. Hammer, C. Hargus, E. D. Hermes, P. C. Jennings, P. B. Jensen, J. Kermode, J. R. Kitchin, E. L. Kolsbjerg, J. Kubal, K. Kaasbjerg, S. Lysgaard, J. B. Maronsson, T. Maxson, T. Olsen, L. Pastewka, A. Peterson, C. Rostgaard, J. Schiøtz, O. Schütt, M. Strange, K. S. Thygesen, T. Vegge, L. Vilhelmsen, M. Walter, Z. Zeng, and K. W. Jacobsen, “The atomic simulation environment—a python library for work- ing with atoms,” Journal of Physics: Condensed Matter 29, 273002 (2017).\n", "- LAMMPS: S. Plimpton, Fast Parallel Algorithms for Short-Range Molecular Dynamics, J Comp Phys, 117, 1-19 (1995).\n", "- Quantum Espresso: P Giannozzi, O Andreussi, T Brumme, O Bunau, M Buongiorno Nardelli, M Calandra, R Car, C Cavazzoni, D Ceresoli, M Cococcioni, N Colonna, I Carnimeo, A Dal Corso, S de Gironcoli, P Delugas, R A DiStasio Jr, A Ferretti, A Floris, G Fratesi, G Fugallo, R Gebauer, U Gerstmann, F Giustino, T Gorni, J Jia, M Kawamura, H-Y Ko, A Kokalj, E Küçükbenli, M Lazzeri, M Marsili, N Marzari, F Mauri, N L Nguyen, H-V Nguyen, A Otero-de-la-Roza, L Paulatto, S Poncé, D Rocca, R Sabatini, B Santra, M Schlipf, A P Seitsonen, A Smogunov, I Timrov, T Thonhauser, P Umari, N Vast, X Wu and S Baroni, J.Phys.:Condens.Matter 29, 465901 (2017)\n", "- HiPhive: The Hiphive Package for the Extraction of High‐Order Force Constants by Machine Learning, Fredrik Eriksson, Erik Fransson, and Paul Erhart, Advanced Theory and Simulations, (2019)\n", "\n", "### Project template\n", "\n", "Project template from the [Computational Molecular Science Python Cookiecutter](https://github.com/molssi/cookiecutter-cms).\n", "\n", "### How to contribute changes\n", "- Clone the repository if you have write access to the main repo, fork the repository if you are a collaborator.\n", "- Make a new branch with `git checkout -b {your branch name}`\n", "- Make changes and test your code\n", "- Ensure that the test environment dependencies (`conda-envs`) line up with the build and deploy dependencies (`conda-recipe/meta.yaml`)\n", "- Push the branch to the repo (either the main or your fork) with `git push -u origin {your branch name}`\n", " * Note that `origin` is the default name assigned to the remote, yours may be different\n", "- Make a PR on GitHub with your changes\n", "- We'll review the changes and get your code into the repo after lively discussion!\n", "\n", "\n", "#### Checklist for updates\n", "- [ ] Make sure there is an/are issue(s) opened for your specific update\n", "- [ ] Create the PR, referencing the issue\n", "- [ ] Debug the PR as needed until tests pass\n", "- [ ] Tag the final, debugged version \n", " * `git tag -a X.Y.Z [latest pushed commit] && git push --follow-tags`\n", "- [ ] Get the PR merged in\n", "\n", "#### Versioneer Auto-version\n", "[Versioneer](https://github.com/warner/python-versioneer) will automatically infer what version \n", "is installed by looking at the `git` tags and how many commits ahead this version is. The format follows \n", "[PEP 440](https://www.python.org/dev/peps/pep-0440/) and has the regular expression of:\n", "```regexp\n", "\\d+.\\d+.\\d+(?\\+\\d+-[a-z0-9]+)\n", "```\n", "If the version of this commit is the same as a `git` tag, the installed version is the same as the tag, \n", "e.g. `kaldo-0.1.2`, otherwise it will be appended with `+X` where `X` is the number of commits \n", "ahead from the last tag, and then `-YYYYYY` where the `Y`'s are replaced with the `git` commit hash." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 2 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython2", "version": "2.7.6" } }, "nbformat": 4, "nbformat_minor": 0 }