Preparation for JOSS submission

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,29 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+## Describe the bug
+
+<!-- A clear and concise description of what the bug is. -->
+
+## To Reproduce
+
+<!-- An explicit procedure to reproduce your bug -->
+
+## Expected behavior
+
+<!-- A clear and concise description of what you expected to happen. -->
+
+## Environment
+
+- Python version:
+- Spgrep's version:
+
+## Additional context
+
+<!-- Add any other context about the problem here. -->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,24 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+## Is your feature request related to a problem? Please describe.
+
+<!-- A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] -->
+
+## Describe the solution you'd like
+
+<!-- A clear and concise description of what you want to happen. -->
+
+## Describe alternatives you've considered
+
+<!-- A clear and concise description of any alternative solutions or features you've considered. -->
+
+## Additional context
+
+<!-- Add any other context or screenshots about the feature request here. -->

.github/workflows/draft-pdf.yml

@@ -0,0 +1,34 @@
+name: JOSS draft
+
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - "docs/paper/**"
+  pull_request:
+    branches: [main, develop]
+    paths:
+      - "docs/paper/**"
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Paper Draft
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: docs/paper/paper.md
+      - name: Upload
+        uses: actions/upload-artifact@v3
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: docs/paper/paper.pdf

.github/workflows/testing.yml

@@ -11,6 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
+        # Python 3.11 is blocked by the following issue: https://github.com/h5py/h5py/issues/2146
         python-version: ["3.8", "3.9", "3.10"]
 
     steps:
@@ -49,6 +50,8 @@ jobs:
 
     steps:
     - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
 
     - uses: actions/setup-python@v4
       with:

.gitignore

@@ -135,6 +135,9 @@ docs_build
 .DS_Store
 *.txt
 *.lprof
+*.jats
+*.pdf
+._.*
 
 gh-pages
 gh-pages.pub

.pre-commit-config.yaml

@@ -29,7 +29,7 @@ repos:
       exclude: ^docs/
   # isort
   - repo: https://github.com/pycqa/isort
-    rev: 5.10.1
+    rev: 5.11.4
     hooks:
       - id: isort
         name: isort (python)
@@ -54,6 +54,6 @@ repos:
       files: ^src/spgrep/
   # Notebook
   - repo: https://github.com/nbQA-dev/nbQA
-    rev: 1.5.3
+    rev: 1.6.0
     hooks:
       - id: nbqa-black

README.md

@@ -1,4 +1,4 @@
-# spgrep
+# Spgrep
 [![testing](https://github.com/spglib/spgrep/actions/workflows/testing.yml/badge.svg)](https://github.com/spglib/spgrep/actions/workflows/testing.yml)
 [![pre-commit.ci status](https://results.pre-commit.ci/badge/github/spglib/spgrep/main.svg)](https://results.pre-commit.ci/latest/github/spglib/spgrep/main)
 [![codecov](https://codecov.io/gh/spglib/spgrep/branch/main/graph/badge.svg?token=DQGVFCTB1P)](https://codecov.io/gh/spglib/spgrep)
@@ -8,7 +8,7 @@
 [![PyPI Downloads](https://img.shields.io/pypi/dm/spgrep)](https://img.shields.io/pypi/dm/spgrep)
 ![Lines of code](https://img.shields.io/tokei/lines/github/spglib/spgrep)
 
-**spgrep** is a Python package of on-the-fly generator of space-group irreducible representations.
+**Spgrep** is a Python package of on-the-fly generator of space-group irreducible representations.
 
 - Github: <https://github.com/spglib/spgrep>
 - Document: <https://spglib.github.io/spgrep>
@@ -17,11 +17,12 @@
 
 ## Features
 
-- Calculate irreducible representations (irreps) of space groups from spglib’s cell and kpoints
-- Calculate irreps of crystallographic point groups
-- Calculate physically irreducible representations (irreps over real numbers)
-- Calculate irreducible spin representations
-- Calculate irreducible co-representations
+- Enumerate the following irreducible representations (irreps) of space groups from [spglib](https://spglib.github.io/spglib/)’s cell and kpoints:
+    - Linear irreps
+    - Physically irreps (irreps over real numbers)
+    - Projective irreps for spnior
+    - Projective irreducible co-representations for spinor
+- Enumerate irreps of crystallographic point groups as well
 - Find symmetry-adapted basis forming given irreps
 - Minimal dependencies (numpy and [spglib](https://spglib.github.io/spglib/))
 
@@ -71,11 +72,11 @@ for irrep in irreps:
 # [2.+0.j 0.+0.j 0.+0.j -2.+0.j 0.+0.j 0.+0.j 0.+0.j 0.+0.j]
 ```
 
-See [docs/examples/examples](examples/examples) for more detailed use cases.
+See [example pages](docs/examples/examples) for more detailed use cases and [API summary](docs/api/api_core) for summary of functionalities.
 
 ## Installation
 
-spgrep works with Python3.8+ and can be installed via PyPI:
+Spgrep works with Python3.8+ and can be installed via PyPI:
 ```shell
 pip install spgrep
 ```
@@ -89,44 +90,16 @@ cd spgrep
 pip install -e .
 ```
 
-## License
-
-spgrep is released under a BSD 3-clause license.
-
-## Development
-
-### Installation
-
-```shell
-conda create -n spgrep python=3.10 pip
-conda activate spgrep
-git clone git@github.com:spglib/spgrep.git
-cd spgrep
-pip install -e ".[dev,docs]"
-pre-commit install
-
-# Run pre-commit manually
-pre-commit run --all-file 
-```
+## Change log
 
-### Document
+See the [change log](docs/changelog) for recent changes.
 
-```shell
-sphinx-autobuild docs docs_build
-# open localhost:8000 in your browser
-```
+## How to contribute
 
-### Release
+We welcome any contributions to improve functionalities.
+Please open [issues](https://github.com/spglib/spgrep/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) or create [pull requests](https://github.com/spglib/spgrep/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc).
+See the [development page](docs/development/development) for preparing an environment.
 
-```shell
-# Confirm the version number via `setuptools-scm`
-python -m setuptools_scm
-
-# Update changelog here
-vim docs/changelog.md
+## License
 
-# Push with tag
-git tag <next-version>
-git push origin main
-git push origin --tags
-```
+Spgrep is released under a BSD 3-clause license.

docs/api/api.md

@@ -3,11 +3,11 @@
 ```{toctree}
     Core functions <api_core>
     Group <api_group>
-    Irreps <api_irreps>
     Point group <api_pointgroup>
-    Representation <api_representation>
     Transformation <api_transformation>
-    Tensor <api_tensor>
+    Representation <api_representation>
+    Irreps <api_irreps>
     Spinor <api_spinor>
     Co-representation <api_corep>
+    Tensor <api_tensor>
 ```

docs/api/api_core.md

@@ -1,7 +1,50 @@
 # Core functions
 
+## Summary
+
+Spgrep provides its core functions to enumerate irreducible representations (irreps) from given
+- crystal structures (``(lattice, positions, numbers)``) or magnetic crystal structures (``(lattice, positions, numbers, magmoms)``),
+- symmetry operations of space groups (``(rotations, translations)``) or magnetic space groups (``(rotations, translations, time_reversals)``),
+- and symmetry operations of crystallographic point groups (``rotations``).
+
+For a given crystal structure or symmetry operations, Spgrep calculates the following representations:
+- Linear irreps (See {ref}`space_group_irreps`)
+- Physically irreps (See {ref}`physically_irreps`)
+- Projective irreps for spinor (See {ref}`spin_representation`)
+- Projective irreducible co-representation (co-reps) for spinor (See {ref}`corep`)
+
+The following tables summarize core functions for a combination of representations and inputs.
+
+### Functions for (magnetic) crystal structure
+
+| Tasks                         | (Magnetic) crystal structure                                |
+|-------------------------------|------------------------------------------------------------ |
+| Linear irreps                 | {func}`spgrep.get_spacegroup_irreps`                        |
+| Projective irreps for spinor  | {func}`spgrep.get_spacegroup_spinor_irreps`                 |
+| Projective co-reps for spinor | {func}`spgrep.get_spacegroup_spinor_irreps` with `magmoms`  |
+
+### Functions for (magnetic) space-group symmetry operations
+
+| Tasks                         | (Magnetic) space group                                                                    |
+|-------------------------------|-------------------------------------------------------------------------------------------|
+| Linear irreps                 | {func}`spgrep.get_spacegroup_irreps_from_primitive_symmetry`                              |
+| Physically irreps             | {func}`spgrep.get_spacegroup_irreps_from_primitive_symmetry` with `real=True`             |
+| Projective irreps for spinor  | {func}`spgrep.get_spacegroup_spinor_irreps_from_primitive_symmetry`                       |
+| Projective co-reps for spinor | {func}`spgrep.get_spacegroup_spinor_irreps_from_primitive_symmetry` with `time_reversals` |
+
+### Functions for (magnetic) crystallographic point-group symmetry operations
+
+| Tasks                         | (Magnetic) point group                                                                           |
+|-------------------------------|--------------------------------------------------------------------------------------------------|
+| Linear irreps                 | {func}`spgrep.get_crystallographic_pointgroup_irreps_from_symmetry`                              |
+| Physically irreps             | {func}`spgrep.get_crystallographic_pointgroup_irreps_from_symmetry` with `real=True`             |
+| Projective irreps for spinor  | {func}`spgrep.get_crystallographic_pointgroup_spinor_irreps_from_symmetry`                       |
+| Projective co-reps for spinor | {func}`spgrep.get_crystallographic_pointgroup_spinor_irreps_from_symmetry` with `time_reversals` |
+
 ## Linear representation
 
+### Space group
+
 ```{eval-rst}
     .. autofunction:: spgrep.get_spacegroup_irreps
 ```
@@ -10,12 +53,16 @@
     .. autofunction:: spgrep.get_spacegroup_irreps_from_primitive_symmetry
 ```
 
+### Crystallographic point group
+
 ```{eval-rst}
     .. autofunction:: spgrep.get_crystallographic_pointgroup_irreps_from_symmetry
 ```
 
 ## Spin representation
 
+### Space group
+
 ```{eval-rst}
     .. autofunction:: spgrep.get_spacegroup_spinor_irreps
 ```
@@ -24,6 +71,8 @@
     .. autofunction:: spgrep.get_spacegroup_spinor_irreps_from_primitive_symmetry
 ```
 
+### Crystallographic point group
+
 ```{eval-rst}
     .. autofunction:: spgrep.get_crystallographic_pointgroup_spinor_irreps_from_symmetry
 ```

docs/api/api_group.md

@@ -1,11 +1,23 @@
 # Group
 
 ```{eval-rst}
-    .. autofunction:: spgrep.group.is_matrix_group
+    .. autofunction:: spgrep.group.get_cayley_table
 ```
 
 ```{eval-rst}
-    .. autofunction:: spgrep.group.get_cayley_table
+    .. autofunction:: spgrep.group.get_identity_index
+```
+
+```{eval-rst}
+    .. autofunction:: spgrep.group.get_inverse_index
+```
+
+```{eval-rst}
+    .. autofunction:: spgrep.group.get_order
+```
+
+```{eval-rst}
+    .. autofunction:: spgrep.group.is_matrix_group
 ```
 
 ```{eval-rst}
@@ -16,6 +28,10 @@
     .. autofunction:: spgrep.group.get_little_group
 ```
 
+```{eval-rst}
+    .. autofunction:: spgrep.group.check_cocycle_condition
+```
+
 ```{eval-rst}
     .. autofunction:: spgrep.group.decompose_by_maximal_space_subgroup
 ```

docs/api/api_irreps.md

@@ -23,3 +23,7 @@
 ```{eval-rst}
     .. autofunction:: spgrep.irreps.get_physically_irrep
 ```
+
+```{eval-rst}
+    .. autofunction:: spgrep.irreps.is_equivalent_irrep
+```