diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 59c598e..8bb7339 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -25,16 +25,16 @@ jobs: matrix: python-version: ["3.8","3.9","3.10","3.11"] os: [ubuntu-latest,] - + runs-on: ${{matrix.os}} steps: - uses: actions/checkout@v3 - + - name: Set up Python ${{ matrix.python-version }} uses: actions/setup-python@v4 with: python-version: ${{ matrix.python-version }} - + - name: Install dependencies run: | python -m pip install --upgrade pip @@ -44,16 +44,16 @@ jobs: pip install pytest-cov pip install pytest-mpl pip install -e . - + - name: Check package versions run: | pip show -V pytest pip show -V ase pip show -V matplotlib - + - name: Run tests run: pytest --cov=macrodensity --mpl tests/unit_tests.py --cov-report=xml -v - + - name: Upload coverage to Codecov uses: codecov/codecov-action@v3 with: @@ -61,4 +61,3 @@ jobs: fail_ci_if_error: true verbose: true files: ./coverage.xml - diff --git a/.github/workflows/release_to_pypi.yml b/.github/workflows/release_to_pypi.yml new file mode 100644 index 0000000..486eb11 --- /dev/null +++ b/.github/workflows/release_to_pypi.yml @@ -0,0 +1,56 @@ +name: Release and publish + +on: + workflow_run: + workflows: [ "MacroDensity CI" ] + branches: [ main ] + types: + - completed # only release when tests have passed + + workflow_dispatch: + +jobs: + release: + runs-on: ubuntu-latest + if: ${{ github.event_name == 'workflow_dispatch' || (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success') }} + # only run when tests have passed (or manually triggered) + + steps: + - uses: actions/checkout@v1 + + - uses: actions/setup-python@v1 + with: + python-version: 3.9 + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install setuptools setuptools_scm wheel + pip install -e .[tests] + + - name: Build packages + run: | + python setup.py sdist bdist_wheel + + - name: Publish + uses: pypa/gh-action-pypi-publish@master + with: + user: __token__ + password: ${{ secrets.TWINE_PASSWORD }} + + - name: Generate release info + run: | + awk 'BEGIN {p = 0} {a = 0 }; /^v\d*.\d*.\d*./ { p += 1; a = 1}; p + a == 1 { print } ' CHANGELOG.rst | sed -e '1,1d' | sed -e '/./,$!d' -e :a -e '/^\n*$/{$d;N;ba' -e '}' > release_info.txt + echo "version=$(grep version setup.py | awk -F\" '{print $2}')" >> $GITHUB_ENV + + - name: Release + uses: actions/create-release@v1 + id: create_release + env: + GITHUB_TOKEN: ${{ secrets.PYPI_API_TOKEN }} + with: + tag_name: v${{ env.version }} + release_name: ${{ env.version }} + body_path: release_info.txt + draft: false + prerelease: false diff --git a/CHANGELOG.rst b/CHANGELOG.rst new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/CHANGELOG.rst @@ -0,0 +1 @@ + diff --git a/README.md b/README.md index 481f259..48ace2d 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,23 @@ -MacroDensity -==================== -![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.884521.svg) +# Welcome to MacroDensity -A set of Python scripts to read in a electrostatic potentials and electron densities from electronic structure calculations and plot in a number of ways, including: +``MacroDensity`` is a Python package to post-process electrostatic potential and +electron density files from electronic structure calculations and plot in a number of ways, including: -* Planar average -* Spherical average -* Atom centred average +1. Planar average +2. Spherical average +3. Atom centred average # Statement of Need -To assess the potential utility of novel semiconducting devices (like p-n junctions, heterostructures, surface terminations), it is key to understand how the electrostatic potential and electron density change across the system. However, extraction and useful presentation of this data from the raw output of the simulation can prove cumbersome and often requires the use of visualisation software followed by manual data extraction. This can result in bottlenecks in high throughput screening projects, where the same data extraction procedure is repeatedly applied to large databases of candidate structures. +To assess the potential utility of novel semiconducting devices (like p-n junctions, heterostructures, surface terminations), +it is key to understand how the electrostatic potential and electron density change across the system. +However, extraction and useful presentation of this data from the raw output of the simulation can prove cumbersome and often requires the use of visualisation software followed by manual data extraction. +This can result in bottlenecks in high throughput screening projects, where the same data extraction procedure is repeatedly applied to large databases of candidate structures. -To address this, the Macrodensity package has been developed to post-process the output of ab-initio codes like `VASP`, `FHI-AIMS` and `GULP`. The package contains functions that enable the user to format the data from the `VASP LOCPOT` and `CHGCAR` files, the `FHI-AIMS *.cube` file, and `GULP *.out` file into physically meaningful quantities, which can then be plotted for user interpretation. +To address this, the Macrodensity package has been developed to post-process the output of ab-initio codes like ``VASP``, ``FHI-AIMS`` and ``GULP``. +The package contains functions that enable the user to format the data from the ``VASP`` ``LOCPOT`` and ``CHGCAR`` files, the ``FHI-AIMS`` ``*.cube`` file, +and ``GULP`` ``*.out`` file into physically meaningful quantities, which can then be plotted for user interpretation. -# Requirements - -* [Python](https://www.python.org) -* [Matplotlib](http://matplotlib.org) (to plot results on the fly) -* [ASE](https://wiki.fysik.dtu.dk/ase/) (for atom centred functionality) -* [Pandas](https://pandas.pydata.org/) (optional - for quicker reading speeds; requires pandas 1.2.0 or newer) -* [Jupyter](https://jupyter.org/) (optional - for `.ipynb` notebooks in the [tutorials](https://github.com/WMD-group/MacroDensity/tree/V3.1.0/tutorials)) # Installation @@ -33,6 +30,7 @@ pip install macrodensity ``` ## Developer installation + For development of MacroDensity, you can install a copy of the package from the source directory: ``` @@ -42,17 +40,17 @@ pip install -e . ``` -Literature -======================== +# Literature + For more information on the theory behind the package, please see the following references: - General Approach: Butler, K. T., Hendon, C. H., & Walsh, A. [Electronic chemical potentials of porous Metal–Organic frameworks](https://doi.org/10.1021/ja4110073). *Journal of the American Chemical Society*, 136(7), 2703–2706, 2014 -- Theoretical Background: +- Theoretical Background: * Politzer, P., & Murray, J. S. [The fundamental nature and role of the electrostatic potential in atoms and molecules](https://link.springer.com/article/10.1007/s00214-002-0363-9). *Theoretical Chemistry Accounts*, 108(3), 134–142, 2002 * Peressi, M., Binggeli, N. & Baldereschi, A. [Band engineering at interfaces: theory and numerical experiments](https://iopscience.iop.org/article/10.1088/0022-3727/31/11/002/meta). *Journal of Physics D: Applied Physics*,31(11), 1273, 1998 - Application to MOFs: * Butler, K. T., Hendon, C. H. & Aron Walsh, A. [Electronic Chemical Potentials of Porous Metal–Organic Frameworks](https://doi.org/10.1021/ja4110073). *Journal of the American Chemical Society*, 136(7), 2703–2706, 2014 - + # Contributing @@ -81,4 +79,3 @@ MacroDensity is made available under the MIT License. If you use it in your research, please cite: * Method: Harnett-Caulfield, L., & Walsh, A. [*Journal of Chemical Physics*](https://doi.org/10.1063/5.0044866) 2021 - diff --git a/TODO.md b/TODO.md deleted file mode 100644 index 5b72373..0000000 --- a/TODO.md +++ /dev/null @@ -1,37 +0,0 @@ -# TODO's - -- [x] Checking function docstrings (e.g. should describe what they do, describe inputs/outputs & include type's of input & output variables) -- [x] Testing with GitHub actions -- [x] Formatting & cleanup of files - * Remove unused imports (e.g. if package/function is imported but not used etc) - * Maybe some reorganization and renaming of input files to make it more user-friendly (alpha_tools.py etc)? -- [x] Generate documentation (with `sphinx`) - * Quickstart guide on using `sphinx` [here](https://www.sphinx-doc.org/en/master/usage/quickstart.html) - * The docs should include 3 main pages: - 1. Intro to what the package can do (index.rst) - 2. Python API for main functions (main_functions.rst) - 3. A good tutorial (as Jupyter Notebook) exemplifying the main functions & workflow - * The notebook should combine `Markdown` and `Code` cells to explain the workflow, showing the outputs/plots etc -- [x] Publish docs in `Readthedocs` -- [x] Installation - - [x] Enable `pip` install: this requires adding package to [pypi](https://pypi.org/) -- [x] Update tutorial 1 to rewrite long code snippets as functions -- [x] Checking code & docstrings formatting with linters - * Using the packages `isort`, `black`, `pycodestyle`, `flake8` -- [ ] Write up `JOSS` paper - - Some examples here: - - [Example1](https://joss.theoj.org/papers/10.21105/joss.04817) - - [Example2](https://joss.theoj.org/papers/10.21105/joss.03171) -- [x] Update `tools.spherical_average` and `plotting.plot_on_site_potential` to handle different output files rather than just `LOCPOT`. -- [x] Format line length of docstrings to follow PEP conventions -- [x] Automatically publish version to pypi when a new release is made on GitHub -- [ ] Check which functions are not currently tested in `unit_tests.py` (for instance - `plot_field_at_point`, `plot_plane_field`, `energy_band_alignment_diagram`, `get_band_extrema` are not currently tested). - Can use matplotlib to compare figures as done [here](https://github.com/SMTG-UCL/ShakeNBreak/blob/develop/tests/test_plotting.py#L1038). Add tests for these functions -- [ ] Add [codecov](https://docs.codecov.com/docs#step-5-get-coverage-analysis-from-codecov) badge to README to see how many lines of code are tested -- [ ] Refactor `plot_planar_average` to show coordinate position in x axis rather than grid position -- [ ] Add linting workflow (similar to [this](https://github.com/SMTG-UCL/ShakeNBreak/blob/develop/.github/workflows/lint.yml)) -- [ ] Update conda installation instructions (need to update current conda package, https://anaconda.org/hcc/macrodensity): - * Could look to add the package to the conda-forge channel following the instructions here: https://github.com/conda-forge/staged-recipes - * If you want to update the package on the HCC channel, then the instructions are here though it appears there isn't a recipe for Macrodensity in this repo (probably due to age): https://github.com/unlhcc/hcc-conda-recipes -- [ ] Automatically get lattice vector from `POSCAR`` file, rather than taking it from user input