Metadata-Version: 2.4
Name: crysymdb
Version: 1.0.0
Summary: a crystallographic symmetry database
License-Expression: GPL-3.0-only
License-File: LICENSE
Keywords: crystallography,symmetry
Author: Shu-Hao Cao
Author-email: csh.academic@gmail.com
Requires-Python: >=3.11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Provides-Extra: all
Provides-Extra: cli
Provides-Extra: test
Requires-Dist: bidict
Requires-Dist: moyopy ; extra == "all"
Requires-Dist: moyopy ; extra == "cli"
Requires-Dist: pandas ; extra == "test"
Requires-Dist: pydantic (>=2,<3)
Requires-Dist: pymatgen ; extra == "all"
Requires-Dist: pymatgen ; extra == "cli"
Requires-Dist: pytest ; extra == "test"
Requires-Dist: rich ; extra == "all"
Requires-Dist: rich ; extra == "cli"
Requires-Dist: spglib ; extra == "all"
Requires-Dist: spglib ; extra == "cli"
Requires-Dist: typer ; extra == "all"
Requires-Dist: typer ; extra == "cli"
Project-URL: Changelog, https://github.com/TepLabCode/CrySymDB/blob/main/ChangeLog.md
Project-URL: Homepage, https://github.com/TepLabCode/CrySymDB
Project-URL: Issues, https://github.com/TepLabCode/CrySymDB/issues
Project-URL: Repository, https://github.com/TepLabCode/CrySymDB
Description-Content-Type: text/markdown

# CrySymDB

<p align="center">
  <img src="doc/source/_static/logo.png" style="max-height:250px;" alt="">
</p>
<p align="center">
  <a href="https://pypi.org/project/crysymdb/">
    <img src="https://img.shields.io/pypi/pyversions/crysymdb.svg" alt="Python"></a>
  <a href="https://pypi.org/project/crysymdb/">
    <img src="https://img.shields.io/pypi/v/crysymdb.svg" alt="PyPI"></a>
</p>

<p align="center">
<a href="README.md"><strong>English</strong></a>
  <span> | </span>
  <a href="README_CN.md">简体中文</a>
</p>

**CrySymDB** is a **Cry**stallographic **Sym**metry **D**ata**B**ase in Python.

- GitHub: [CrySymDB | GitHub](https://github.com/TepLabCode/CrySymDB)

---

## Features

- Crystallographic group types:
  - 2 types of line groups
  - 17 types of plane groups
  - 230 types of space groups
  - 7 types of frieze groups
  - 75 types of rod groups
  - 80 types of layer groups
- Arithmetic-Geometric and Arithmetic crystal classes
- Geometric crystal classes (Point group types) and Bravais classes (Bravais lattice types)
- Lattice systems and Crystal systems
- Crystal families
- Reciprocal-space groups with/without additional inversion.
- [`pymatgen`](https://pymatgen.org/), [`spglib`](https://github.com/spglib/spglib), and [`moyo`](https://github.com/spglib/moyo) APIs: for reading structure files and identifying
  their space-group and layer-group types.
- A Typer-based command line interface (CLI)

<p align="center">
<strong>
Classification levels for crystallographic groups
</strong>
</p>

```mermaid
flowchart BT
    CF["Crystal Families"]
    LS["Lattice Systems"]
    CS["Crystal Systems"]
    RLSG[Reciprocal-Lattice-Space Group Types]
    RSG[Reciprocal-Space Group Types]
    BC["Bravais Classes"]
    GCC["Geometric Crystal Classes"]
    ACC["Arithmetic Crystal Classes"]
    AGCC["Arithmetic-Geometric Crystal Classes"]
    G["Direct-Space Group Types"]
    G --> AGCC
    AGCC --> ACC
    AGCC --> RSG
    ACC --> RLSG
    AGCC --> GCC
    ACC --> BC
    BC --> LS
    GCC --> CS
    LS --> CF
    CS --> CF
```

## How To Cite

If CrySymDB helps your research with crystallographic symmetry data or
classification tables, please consider citing our paper. Your citation supports
the continued development and maintenance of CrySymDB:

> The CrySymDB manuscript is currently under submission. Full citation details
> will be added here once the paper is accepted or published.

## Installation

Full installation with all optional dependencies:

```bash
python -m pip install "crysymdb[all]"
```

Minimal core packages only:

```bash
python -m pip install "crysymdb"
```

Core + CLI packages:

```bash
python -m pip install "crysymdb[cli]"
```

## Quick Start

```python
from crysymdb.classification.group import PlaneGroupType, SpaceGroupType

pg = PlaneGroupType.from_symbol("p4mm")
print(pg.number)          # 11
print(pg.crystal_system)  # Square
print(pg.bravais_class)   # Square (tp)

sg = SpaceGroupType(225)
print(sg.symbol)                  # Fm-3m
print(sg.crystal_family)          # Cubic (c)
print(sg.reciprocal_space_group)  # Im-3m (No. 229)
```

Use `as_dict(string_values=True)` when you need a serializable summary of the
most important derived fields:

```python
from crysymdb.classification.group import PlaneGroupType

group = PlaneGroupType.from_symbol("p4mm")
data = group.as_dict(string_values=True)

print(data["group_symbol"])                          # p4mm
print(data["arithmetic_geometric_crystal_class"])    # 4mmp (No. 8)
print(data["reciprocal_space_group_with_inversion"]) # p4mm (No. 11)
```

## Examples

The [`examples`](examples) directory includes pre-exported CSV and Excel tables
that can be used directly without installing CrySymDB as a Python package:

- [`examples/csv`](examples/csv): CSV files split by group family.
- [`examples/group_classification_tables.xlsx`](examples/group_classification_tables.xlsx):
  an Excel workbook with one sheet per group family and every cell left
  unmerged for sorting, filtering, or programmatic processing.
- [`examples/group_classification_tables_(merged).xlsx`](examples/group_classification_tables_\(merged\).xlsx):
  the same workbook with vertically repeated cells merged.

The directory also provides
[`examples/get_group_tables.py`](examples/get_group_tables.py), which shows how
these files are generated from the CrySymDB group databases. You can use it as a
template if you want to regenerate the tables or customize the exported columns.

## CLI Usage

The package defines two equivalent console entries:

```bash
crysymdb --help
```
and for short:

```bash
csdb --help
```

You can look up classification information for a crystallographic group using its number or symbol.:

```bash
csdb group plane p4mm
csdb group space 225
```

You can also read a structure file and identify its symmetry:

```bash
csdb file-sg path/to/structure.cif --symprec 1e-5 --angle-tolerance 5
csdb file-lg path/to/structure.cif --symprec 1e-5 --angle-tolerance 5
```

For CLI commands, `--angle-tolerance` is given in degrees.

There are six different commands available now:

- `file-sg` or `f-sg`: read a structure file, determine its space group with
  `moyo`, and print CrySymDB classification data.
- `file-lg` or `f-lg`: read a structure file, determine its layer group with
  `moyo`, and print CrySymDB classification data.
- `file-sg-spglib` or `f-sg-s`: print the raw space-group dataset returned by
  `spglib`.
- `file-lg-spglib` or `f-lg-s`: print the raw layer-group dataset returned by
  `spglib`.
- `file-sg-moyo` or `f-sg-m`: print the raw space-group dataset returned by
  `moyo`.
- `file-lg-moyo` or `f-lg-m`: print the raw layer-group dataset returned by
  `moyo`.

Add `--raw` to file commands to print the underlying dictionary representation
instead of the default formatted output.

## Project Structure

```text
src/crysymdb/
  classification/   Dataclass models for groups and crystal classifications.
  data/             Static symbol and mapping tables used by the models.
  interface/        Interfaces to external libraries (pymatgen, spglib, moyo).
  cli/typer/        Typer command line application.
  types.py          Shared type aliases.
  py.typed          PEP 561 type marker.
doc/source/_static/
  logo.png          Logo used by this README.
```

## Testing

Run the test commands from the project root directory, which contains
`pyproject.toml`:

```bash
cd path/to/CrySymDB
```

Install the package with the test dependencies:

```bash
python -m pip install -e ".[test]"
```

Run the test suite:

```bash
python -m pytest
```

CLI tests are skipped unless the optional CLI dependencies are installed:

```bash
python -m pip install -e ".[test,cli]"
python -m pytest
```

## Future plans

- Add a test suite for the classification models and CLI commands.
- Support the TeX format of symbols.
- Support the full Hermann-Mauguin symbol of groups.
- Support the Wyckoff position data of groups.
- ...

Contributions are welcome if you have ideas about any of the above or other directions.

## License

**CrySymDB** is distributed under the **GNU General Public License v3.0**.
See [LICENSE](LICENSE).

## Bug Reports & Feedback

If you encounter any bugs or have any feedback or suggestions,  
please feel free to report them by opening an
[Issue](https://github.com/TepLabCode/CrySymDB/issues/new).

