Package: atoMEC
atoMEC: Average-Atom Code for Matter under Extreme ConditionsatoMEC is a python-based average-atom code for simulations of high energy density phenomena such as in warm dense matter.
It is designed as an open-source and modular python package.atoMEC uses Kohn-Sham density functional theory, in combination with an average-atom approximation,
to solve the electronic structure problem for single-element materials at finite temperature.More information on the average-atom methodology and Kohn-Sham density functional theory can be found (for example) in thispaperand references therein.This repository is structured as follows:├── atoMEC : source code
├── docs : sphinx documentation
├── examples : simple examples to get you started with the package
└── tests : CI testsInstallationThe latest stable release ofatoMECcan be installed viapip. It is first necessary to install thelibxcpackage from a tarball source, because it currently has no official wheels distribution on PyPI. This step takes some time.$pipinstallhttps://gitlab.com/libxc/libxc/-/archive/6.2.2/libxc-6.2.2.tar.gz
$pipinstallatoMECNote that atoMEC does not (yet) support Windows installation (please see the section below on supported operating systems).Read on for instructions on how to installatoMECfrom source, using the recommendedpipenvinstallation route.Installation viapipenvFirst, clone the atoMEC repository andcdinto the main directory.It is recommended to install atoMEC inside a virtual environment. Below, we detail how to achive this withpipenv.This route is recommended becausepipenvautomatically creates a virtual environment and manages dependencies. Note thatpyblibxcis automatically installed in this case, so there is no need to install it separately.First, installpipenvif it is not already installed, for example viapip install pipenv(or seepipenvfor installation instructions)Next, installatoMEC's dependencies withpipenv install(use--devoption to install the test dependencies in the same environment)Usepipenv shellto activate the virtual environmentInstall atoMEC withpip install atoMEC(for developers:pip install -e .)Now run scripts from inside theatoMECvirtual environment, e.g.python examples/simple.pyRun the tests (see Testing section below) and report any failures (for example by raising an issue).Supported operating systemsLinux and macOS: atoMEC has been installed on various linux distributions and macOS, and is expected to work for most distributions and versionsWindows: atoMEC doesnotsupport Windows installation. This is due to the dependency onpylibxcwhich currently lacks Windows support. We are looking into ways to make the dependency onpylibxcoptional, in order to allow installation on Windows. However, this is not currently a priority.Supported Python versionsatoMEC has been tested and is expected to work for all Python versions >= 3.8 and <= 3.12atoMEC does not work for Python <= 3.7Until 09.10.2023 (release 1.4.0), all development and CI testing was done with Python 3.8. As of this date, development and CI testing is done with Python 3.12.Python 3.12 is therefore the recommended version for atoMEC >= 1.4.0, since this is used for the current testing and development environmentRunningYou can familiarize yourself with the usage of this package by running the example scripts inexamples/.Contributing to atoMECWe welcome your contributions, please adhere to the following guidelines when contributing to the code:In general, contributors should develop on branches based off ofdevelopand merge requests should be todevelopPlease choose a descriptive branch nameMerges fromdeveloptomasterwill be done after prior consultation of the core development teamMerges fromdeveloptomasterare only done for code releases. This way we always have a cleanmasterthat reflects the current releaseCode should be formatted usingblackstyleTestingFirst, install the test requirements (if not already installed in the virtual env withpipenv install --dev):# activate environment first (optional)$pipenvshell# install atoMEC as editable project in current directory (for developers)$pipinstall-e.[tests]# alternatively install package from PyPI with test dependencies$pipinstallatoMEC[tests]To run the tests:$pytest--cov=atoMEC--random-ordertests/Build documentation locally (for developers)Install the prerequisites:$pipinstall-rdocs/requirements.txtChange intodocs/folder.Runmake apidocs.Runmake html. This creates a_buildfolder insidedocs. You may also want to usemake html SPHINXOPTS="-W"sometimes. This treats warnings as errors and stops the output at first occurrence of an error (useful for debugging rST syntax).Opendocs/_build/html/index.html.make cleanif required (e.g. after fixing errors) and building again.DevelopersScientific SupervisionAttila Cangi (Center for Advanced Systems Understanding)Eli Kraisler (Hebrew University of Jerusalem)Core Developers and MaintainersTim Callow (Center for Advanced Systems Understanding)Daniel Kotik (Center for Advanced Systems Understanding)Contributions (alphabetical)Nathan Rahat (Hebrew University of Jerusalem)Ekaterina Tsvetoslavova Stankulova (Center for Advanced Systems Understanding)Citing atoMECIf you use code from this repository in a published work, please citeT. J. Callow, D. Kotik, E. Kraisler, and A. Cangi, "atoMEC: An open-source average-atom Python code",Proceedings of the 21st Python in Science Conference, edited by Meghann Agarwal, Chris Calloway, Dillon Niederhut, and David Shupe (2022), pp. 31 – 39The DOI corresponding to the specific version of atoMEC that you used (DOIs are listed atZenodo.org)