Merge pull request #109 from atomec-project/develop

Make new release 1.1.0

.gitattributes

@@ -0,0 +1 @@
+*.cff   linguist-language=YAML

.github/workflows/gh-pages.yml

@@ -1,6 +1,8 @@
 name: docs
 
 on:
+  pull_request_review:
+    types: [submitted,edited]
   pull_request:
     branches:
       - master
@@ -61,7 +63,8 @@ jobs:
           mv -v docs/_build/html public
 
       - name: Deploy
+        if: ${{ github.event.review.state == 'approved' || github.event_name == 'push' }}
         uses: peaceiris/actions-gh-pages@v3
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
+          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
           publish_dir: ./public

.github/workflows/mirror.yml

@@ -0,0 +1,16 @@
+name: mirror
+
+on: [push, delete]
+
+jobs:
+  mirror-to-CASUS:
+    runs-on: ubuntu-18.04
+    steps:
+    - uses: actions/checkout@v1
+    - name: mirror-repository
+      uses: spyoungtech/mirror-action@v0.4.0
+      with:
+        REMOTE: git@github.com:casus/atoMEC.git
+        GIT_SSH_PRIVATE_KEY: ${{ secrets.GIT_SSH_KEY }}
+        GIT_SSH_NO_VERIFY_HOST: "true"
+        DEBUG: "true"

.github/workflows/publish-to-test-pypi.yml

@@ -0,0 +1,55 @@
+name: Publish Python 🐍 distributions 📦 to PyPI and TestPyPI
+
+on:
+  push:
+    branches:
+      - master
+      - develop
+
+jobs:
+  build-n-publish:
+    name: Build and publish Python 🐍 distributions 📦 to PyPI and TestPyPI
+    runs-on: ubuntu-18.04
+    steps:
+    - name: Check out repository
+      uses: actions/checkout@v2
+
+    - name: Set up Python 3.8
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.8'
+
+    - name: Install pypa/build
+      run: >-
+        python -m
+        pip install
+        build
+        --user
+
+    - name: Build a binary wheel and a source tarball
+      run: >-
+        python -m
+        build
+        --sdist
+        --wheel
+        --outdir dist/
+        .
+
+    - name: Publish distribution 📦 to Test PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+        repository_url: https://test.pypi.org/legacy/
+        verbose: true
+        skip_existing: true
+
+    - name: Publish distribution 📦 to PyPI
+      # trigger only for tagged commits
+      # NB: this is also true for tagged commits on develop!
+      if: startsWith(github.ref, 'refs/tags')
+      # NB: another option could be:
+      # if: github.event_name == 'release' && github.event.action == 'created'
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        password: ${{ secrets.PYPI_API_TOKEN }}
+        verbose: true

CITATION.cff

@@ -3,18 +3,22 @@ authors:
   - affiliation: "Center for Advanced Systems Understanding (CASUS), Helmholtz-Zentrum Dresden-Rossendorf e.V. (HZDR)"
     family-names: Callow
     given-names: Timothy
+    orchid: https://orcid.org/0000-0002-4878-3521
   - affiliation: "Center for Advanced Systems Understanding (CASUS), Helmholtz-Zentrum Dresden-Rossendorf e.V. (HZDR)"
     family-names: Kotik
     given-names: Daniel
+    orcid: https://orcid.org/0000-0001-8735-3199
   - affiliation: "Center for Advanced Systems Understanding (CASUS), Helmholtz-Zentrum Dresden-Rossendorf e.V. (HZDR)"
     family-names: Tsvetoslavova Stankulova
     given-names: Ekaterina
   - affiliation: "Fritz Haber Center for Molecular Dynamics and Institute of Chemistry, The Hebrew University of Jerusalem"
     family-names: Kraisler
     given-names: Eli
+    orchid: https://orcid.org/0000-0003-0139-258X
   - affiliation: "Center for Advanced Systems Understanding (CASUS), Helmholtz-Zentrum Dresden-Rossendorf e.V. (HZDR)"
     family-names: Cangi
     given-names: Attila
+    orchid: https://orcid.org/0000-0001-9162-262X
 cff-version: 1.1.0
 date-released: 2021-08-16
 keywords:

README.md

@@ -1,10 +1,13 @@
+![image](./docs/source/img/logos/atoMEC_horizontal2.png)
+
+# atoMEC: Average-Atom Code for Matter under Extreme Conditions
+
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5205719.svg)](https://doi.org/10.5281/zenodo.5205719)
 [![docs](https://github.com/atomec-project/atoMEC/actions/workflows/gh-pages.yml/badge.svg)](https://github.com/atomec-project/atoMEC/actions/workflows/gh-pages.yml)
 [![image](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![PyPI version](https://badge.fury.io/py/atoMEC.svg)](https://badge.fury.io/py/atoMEC)
 
-
-# atoMEC: Average-Atom Code for Matter under Extreme Conditions
 atoMEC 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.
 
@@ -31,7 +34,7 @@ First, clone the atoMEC repository and ``cd`` into the main directory.
 
   1. First, install `pipenv` if it is not already installed, for example via `pip install pipenv` (or see [pipenv](https://pypi.org/project/pipenv/) for    installation instructions)
   2. Next, install `atoMEC`'s dependencies with `pipenv install`
-  3. Use `pipenv shell` to activate the virtual environment and install atoMEC with `pip install -e .`
+  3. Use `pipenv shell` to activate the virtual environment and install atoMEC with `pip install atoMEC` (for developers: `pip install -e .`)
   4. Now run scripts from inside the `atoMEC` virtual environment, e.g. `python examples/simple.py`
 
 * Try running the examples in `examples/` and report any problems
@@ -56,7 +59,7 @@ $ pip install -r docs/requirements.txt
 
 1. Change into `docs/` folder.
 2. Run `make apidocs`.
-3. Run `make html`. This creates a `_build` folder inside `docs`. You may also want to use `make html SPHINXOPTS="-W"` sometimes. This treats warnings as errors and stops the output at first occurence of an error (useful for debugging rST syntax).
+3. Run `make html`. This creates a `_build` folder inside `docs`. You may also want to use `make html SPHINXOPTS="-W"` sometimes. This treats warnings as errors and stops the output at first occurrence of an error (useful for debugging rST syntax).
 4. Open `docs/_build/html/index.html`.
 5. `make clean` if required (e.g. after fixing errors) and building again.
 
@@ -74,6 +77,8 @@ $ pip install -r docs/requirements.txt
 - Ekaterina Tsvetoslavova Stankulova ([Center for Advanced Systems Understanding](https://www.casus.science/))
 
 ## Citing atoMEC
-The following paper should be cited in publications which use atoMEC:
+If you use code from this repository in a published work, please cite the DOI corresponding to the specific version of atoMEC that you used (DOIs are listed at [Zenodo.org](https://doi.org/10.5281/zenodo.5205718)).
+
+If appropriate, you might also consider citing the following preprint in publications which use atoMEC:
 
 T. J. Callow, E. Kraisler, S. B. Hansen, and A. Cangi, (2021). First-principles derivation and properties of density-functional average-atom models. arXiv preprint [arXiv:2103.09928](https://arxiv.org/abs/2103.09928).

atoMEC/__init__.py

@@ -4,15 +4,15 @@
 Copyright (c) 2021 (in alphabetical order), Tim Callow, Attila Cangi, Eli Kraisler.
 All rights reserved.
 
-atoMEC is a python-based average-atom code for simulations of high energy density \
+atoMEC is a python-based average-atom code for simulations of high energy density
 phenomena such as in warm dense matter.
-Please see the README or the project wiki (https://atomec-project.github.io/atoMEC/) \
+Please see the README or the project wiki (https://atomec-project.github.io/atoMEC/)
 for more information.
 
 Classes
 -------
 * :class:`Atom` : the main object for atoMEC calculations, containing information \
-about physical material properties
+                  about physical material properties
 """
 
 __version__ = "1.0.0"
@@ -120,6 +120,11 @@ def at_mass(self):
         """float: the atomic mass (in a.u.)."""
         return self.species.atomic_weight
 
+    @property
+    def nvalence(self):
+        """int: the number of valence electrons."""
+        return self.species.nvalence()
+
     @property
     def units_temp(self):
         """str: the units of temperature."""
@@ -178,7 +183,7 @@ def units_density(self, units_density):
 
     @property
     def radius(self):
-        r"""float: radius of the Wigner-Seitz sphere.
+        r"""float: radius of the Voronoi sphere.
 
         The radius is defined as :math:`a_i /2`,
         where :math:`a_i` is the average inter-atomic distance.
@@ -204,6 +209,30 @@ def density(self, density):
         config.r_s = self._radius
         config.sph_vol = (4.0 * pi * self._radius ** 3.0) / 3.0
 
+    @property
+    def WS_radius(self):
+        r"""float: the Wigner-Seitz radius, or the electron coupling parameter.
+
+        The Wigner-Seitz radius differs from the Voronoi radius because it depends on
+        the free electron density, defined in atoMEC as the valence electron density.
+        """
+        return self.radius * self.nvalence ** (-1.0 / 3.0)
+
+    @property
+    def E_Fermi(self):
+        r"""float: the Fermi energy."""
+        return 0.5 * (9.0 * pi / 4.0) ** (2.0 / 3.0) * self.WS_radius ** -2.0
+
+    @property
+    def gamma_ion(self):
+        r"""float: the ionic coupling parameter."""
+        return self.at_chrg ** 2.0 / (2.0 * self.radius * self.temp)
+
+    @property
+    def theta_e(self):
+        r"""float: the electron degeneracy parameter."""
+        return self.temp / self.E_Fermi
+
     @property
     def info(self):
         """str: formatted information about the :obj:`Atom`'s attributes."""

atoMEC/check_inputs.py

@@ -8,8 +8,8 @@
 -------
 * :class:`Atom` : Check the inputs from the :class:`atoMEC.Atom` object.
 * :class:`ISModel` : Check the inputs from the :obj:`atoMEC.models.ISModel` class.
-* :class:`EnergyCalcs` : Check the inputs from the\
- :func:`atoMEC.models.ISModel.CalcEnergy` function.
+* :class:`EnergyCalcs` : Check the inputs from the \
+                         :func:`atoMEC.models.ISModel.CalcEnergy` function.
 * :class:`InputError` : Exit atoMEC and print relevant input error message.
 * :class:`InputWarning` : Warn if inputs are considered outside of typical ranges.
 """
@@ -463,7 +463,7 @@ def check_unbound(unbound):
             if the treatment of unbound electrons is not a valid input
         """
         # list all possible treatments for unbound electrons
-        unbound_permitted = ["ideal"]
+        unbound_permitted = ["ideal", "quantum"]
 
         # convert unbound to all lowercase
         unbound.lower()
@@ -666,9 +666,11 @@ def check_grid_params(grid_params):
         grid_params : dict
             dictionary of grid parameters as follows:
             {
-            `ngrid` (``int``)   : number of grid points,
-            `x0`    (``float``) : LHS grid point takes form
+            `ngrid` (``int``)        : number of grid points,
+            `x0`    (``float``)      : LHS grid point takes form
             :math:`r_0=\exp(x_0)`; :math:`x_0` can be specified
+            `ngrid_coarse` (``int``) : (smaller) number of grid points for estimation
+            of eigenvalues with full diagonalization
             }
 
         Raises
@@ -678,7 +680,7 @@ def check_grid_params(grid_params):
         InputError.ngrid_warning
             if `ngrid` is outside a reasonable convergence range
         """
-        # First assign the keys ngrid and x0 if they are not given
+        # First assign the keys ngrid, x0 and ngrid_coarse if they are not given
         try:
             ngrid = grid_params["ngrid"]
         except KeyError:
@@ -689,6 +691,11 @@ def check_grid_params(grid_params):
         except KeyError:
             x0 = config.grid_params["x0"]
 
+        try:
+            ngrid_coarse = grid_params["ngrid_coarse"]
+        except KeyError:
+            ngrid_coarse = config.grid_params["ngrid_coarse"]
+
         # check that ngrid is an integer
         if not isinstance(ngrid, intc):
             raise InputError.grid_error("Number of grid points not an integer!")
@@ -700,13 +707,24 @@ def check_grid_params(grid_params):
         elif ngrid > 5000:
             print(InputWarning.ngrid_warning("high", "expensive"))
 
+        # check that ngrid_coarse is an integer
+        if not isinstance(ngrid_coarse, intc):
+            raise InputError.grid_error("Number of coarse grid points not an integer!")
+        # check that ngrid_coarse is a positive number
+        if ngrid_coarse < 0:
+            raise InputError.grid_error("Number of coarse grid points must be positive")
+        elif ngrid_coarse < 100:
+            print(InputWarning.ngrid_warning("low", "inaccurate"))
+        elif ngrid_coarse > 500:
+            print(InputWarning.ngrid_warning("high", "expensive"))
+
         # check that x0 is reasonable
         if x0 > -3:
             raise InputError.grid_error(
                 "x0 is too high, calculation will likely not converge"
             )
 
-        grid_params = {"ngrid": ngrid, "x0": x0}
+        grid_params = {"ngrid": ngrid, "x0": x0, "ngrid_coarse": ngrid_coarse}
 
         return grid_params
 
@@ -726,9 +744,10 @@ def check_conv_params(input_params):
         conv_params : dict of floats
             dictionary of convergence parameters as follows:
             {
-            `econv` (``float``) : convergence for total energy,
-            `nconv` (``float``) : convergence for density,
-            `vconv` (``float``) : convergence for electron number
+            `econv` (``float``)  : convergence for total energy,
+            `nconv` (``float``)  : convergence for density,
+            `vconv` (``float``)  : convergence for electron number,
+            `eigtol` (``float``) : tolerance for eigenvalues
             }
 
         Raises
@@ -738,7 +757,7 @@ def check_conv_params(input_params):
         """
         conv_params = {}
         # loop through the convergence parameters
-        for conv in ["econv", "nconv", "vconv"]:
+        for conv in ["econv", "nconv", "vconv", "eigtol"]:
             # assign value if not given
             try:
                 x_conv = input_params[conv]

atoMEC/config.py

@@ -12,9 +12,9 @@
 v_shift = True  # whether to shift the KS potential vertically
 
 # numerical grid for static calculations
-grid_params = {"ngrid": 1000, "x0": -12}
+grid_params = {"ngrid": 1000, "x0": -12, "ngrid_coarse": 300}
 # convergence parameters for static calculations
-conv_params = {"econv": 1.0e-5, "nconv": 1.0e-4, "vconv": 1.0e-4}
+conv_params = {"econv": 1.0e-5, "nconv": 1.0e-4, "vconv": 1.0e-4, "eigtol": 1.0e-4}
 # scf parameters
 scf_params = {"maxscf": 50, "mixfrac": 0.3}
 

atoMEC/convergence.py

@@ -1,13 +1,13 @@
 """
 Contains classes and functions used to compute and store aspects related to convergence.
 
-So far, the only procedure requring convergence is the static SCF cycle. More will \
+So far, the only procedure requring convergence is the static SCF cycle. More will
 be added in future.
 
 Classes
 -------
 * :class:`SCF` : holds the SCF convergence attributes and calculates them for the \
-given cycle
+                 given cycle
 """
 
 # standard libraries