Merge pull request #1 from kousuke-nakano/devel

Transfered SHRY project from a personal account to the organization one

.github/workflows/shry-deploy-test.yml

@@ -0,0 +1,36 @@
+name: Publish Python distributions to test-PyPI
+on:
+  push:
+    branches: [ "master" ]
+
+  workflow_dispatch:
+
+jobs:
+  deploy-pypi:
+    if: github.repository == 'shry-project/SHRY'
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+        with:
+            fetch-depth: 0
+
+      - name: Set up Python 3.9
+        uses: actions/setup-python@v3
+        with:
+            python-version: '3.9'
+
+      - name: Install pypa/build
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install setuptools setuptools_scm wheel
+          python setup.py sdist bdist_wheel
+ 
+      - name: Publish distribution to Test PyPI
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+            user: __token__
+            password: ${{ secrets.TEST_PYPI_SHRY_TOKEN }}
+            repository_url: https://test.pypi.org/legacy/
+            verbose: true

.github/workflows/shry-deploy.yml

@@ -0,0 +1,35 @@
+name: Publish Python distributions to PyPI
+on:
+  release:
+    types: [published]
+
+  workflow_dispatch:
+
+jobs:
+  deploy-pypi:
+    if: github.repository == 'shry-project/SHRY'
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+        with:
+            fetch-depth: 0
+
+      - name: Set up Python 3.9
+        uses: actions/setup-python@v3
+        with:
+            python-version: '3.9'
+
+      - name: Install pypa/build
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install setuptools setuptools_scm wheel
+          python setup.py sdist bdist_wheel
+        
+      - name: Publish distribution to PyPI
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+            user: __token__
+            password: ${{ secrets.PYPI_SHRY_TOKEN }}
+            verbose: true

.github/workflows/shry-pytest.yml

@@ -0,0 +1,41 @@
+# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: SHRY pytest
+
+on:
+  push:
+    branches: [ "master", "devel" ]
+  pull_request:
+    branches: [ "main", "devel" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.7", "3.8", "3.9", "3.10"]
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install flake8 pytest
+        python -m pip install .
+    - name: Lint with flake8
+      run: |
+        # stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+    - name: Test with pytest
+      run: |
+        pytest -v
+
+

.gitignore

@@ -0,0 +1,27 @@
+# swap and cache files
+*.pyc
+*.swp
+*~
+__pycache__
+*temp*
+*.egg-info*
+*.DS_Store
+*.pkl
+dist
+
+# generated structure from tests
+tests/*/structures*
+examples/structures*
+
+# self-testing files
+*rubbish*
+
+# catch-all for all hidden files
+.
+
+# IDE-related files
+.vscode
+.env
+
+# version control
+_version.py

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 SHRY project
+Copyright (c) 2021-, The SHRY Project
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.rst

@@ -0,0 +1,183 @@
+README
+==========
+
+|logo|
+
+|license| |DL| |release| |PYPI_version| |Python_version| |workflows| |fork| |stars|
+
+.. |logo| image:: https://github.com/shry-project/SHRY/blob/master/logo/logo.jpg?raw=true
+.. |license| image:: https://img.shields.io/github/license/shry-project/SHRY
+.. |release| image:: https://img.shields.io/github/release/shry-project/SHRY/all.svg
+.. |DL| image:: https://img.shields.io/pypi/dm/SHRY
+.. |Python_version| image:: https://img.shields.io/pypi/pyversions/SHRY
+.. |fork| image:: https://img.shields.io/github/forks/shry-project/SHRY?style=social
+.. |stars| image:: https://img.shields.io/github/stars/shry-project/SHRY?style=social
+.. |workflows| image:: https://github.com/shry-project/SHRY/actions/workflows/shry-pytest.yml/badge.svg
+.. |PyPI_version| image:: https://badge.fury.io/py/SHRY.svg
+
+SHRY (\ **S**\ uite for \ **H**\ igh-th\ **r**\ oughput generation of models
+with atomic substitutions implemented by p\ **y**\ thon)
+is a tool for generating unique ordered structures
+corresponding to a given disordered structure.
+
+How to cite
+-------------
+Please cite the following paper:
+
+`SHRY: Application of Canonical Augmentation to the Atomic Substitution Problem <https://doi.org/10.1021/acs.jcim.2c00389>`_, G.I. Prayogo*, A. Tirelli, K. Utimula, K. Hongo, R. Maezono, and K. Nakano*, *J. Chem. Inf. Model.*, 62, 2909-2915 (2022), `DOI:10.1021/acs.jcim.2c00389 <https://doi.org/10.1021/acs.jcim.2c00389>`_
+
+Installation
+------------
+
+SHRY can be obtained from PyPI
+
+.. code-block:: console
+
+    pip install shry
+
+For Windows Users
+^^^^^^^^^^^^^^^^^
+
+For Windows users,
+if you don't have Python already,
+you can try, for example,
+installing Python from the Microsoft store
+following instructions on
+`this page`_.
+
+.. _`this page`: https://docs.microsoft.com/en-us/windows/python/beginners
+
+Then install SHRY just like above
+within PowerShell or your favourite terminal.
+
+.. code-block:: console
+
+    pip install shry
+
+Development
+^^^^^^^^^^^
+
+If you prefer to install from source,
+instead follow the procedures below.
+
+.. code-block:: console
+
+    git clone https://github.com/shry-project/SHRY.git
+    cd shry
+    pip install -e .
+
+Quick use
+---------
+
+Preparation of an input file (a CIF file)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can prepare a CIF file with partial occupations.
+
+.. code-block::
+
+    # label element x y z occupation
+    Sm1 Sm 0.000 0.00 0.00 1.000
+    Fe1 Fe 0.250 0.25 0.25 0.400
+    Nb1 Nb 0.250 0.25 0.25 0.600
+    Fe2 Fe 0.278 0.50 0.00 1.000
+
+``SHRY`` will automatically stop if the total occupancy of a site is
+either less or more than 1.0. To simulate vacancies, create a pseudo
+atom with species ``X``.
+
+Check total symmetry-inequivalent structures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can readily check the number of total symmetry-inquivalent
+structures using the following command.
+
+.. code-block:: console
+
+    shry --count-only STRUCTURE_CIF
+
+This operation is based on Polya enumeration and takes much less time
+than a proper generation.
+
+Creating supercell
+^^^^^^^^^^^^^^^^^^
+
+Sometimes a supercell is required to fit in finer concentrations.
+``SHRY`` accepts either 3-digit (diagonal) or 9-digit (non-diagonal)
+format to specify the supercell's scaling matrix. For example a 2x2x1
+supercell can be specified by either
+
+.. code-block:: console
+
+    shry -s 2 2 1 --count-only STRUCTURE_CIF
+
+or
+
+.. code-block:: console
+
+    shry -s 2 0 0 0 2 0 0 0 1 --count-only STRUCTURE_CIF
+
+Generating unique structures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Finally, you can generate symmetry-inequivalent structures using the
+following command:
+
+.. code-block:: console
+
+    shry -s 2 2 1 STRUCTURE_CIF
+
+The generated symmetry-inequivalent structures are saved in sliceXX
+directories.
+
+Additional information
+^^^^^^^^^^^^^^^^^^^^^^
+
+For additional information, you can use the help command:
+
+.. code-block:: console
+
+    shry -h
+
+or you can refer to the documentation.
+
+Documentation
+-------------
+
+The documentation is available `here <https://shry.readthedocs.io/en/latest/>`_.
+
+How to release
+--------------
+
+Work on the devel or on a new branch
+
+.. code-block:: console
+    
+    git merge <new branch> devel # if you work on a new branch.
+    git push origin devel # A GitHub Action triggers pytests.
+
+Check the next-version version
+
+.. code-block:: console
+
+    # Confirm the version number via `setuptools-scm`
+    python -m setuptools_scm
+    e.g., 1.1.4.dev28+gceef293.d20221123 -> <next-version> = v1.1.4 or v1.1.4-alpha(for pre-release)
+
+Add and push with the new tag
+
+.. code-block:: console
+
+    # Push with tag
+    git tag <next-version>  # e.g., git tag v1.1.4  # Do not forget "v" before the version number!
+    git push origin devel --tags  # or to the new branch
+
+Send a pull request to the master branch on GitHub. After the pull request is approved and the devel branch is merged to the master, a GitHub Action checks if the automatic deploy works using test-pyPI (only if the commit is tagged correctly, e.g., v1.1.0).
+
+Finally, do a new release with a release note on GitHub. The new release triggers an implemented GitHub Action that automatically uploads the package to PyPI (if the commit is tagged correctly, e.g., v1.1.0).
+
+Contributing to the project
+---------------------------
+
+If you want to contribute to the project, report a bug, or ask for
+a new feature, please `raise an issue <https://github.com/shry-project/SHRY/issues>`_.