crysymdb 1.0.0

a crystallographic symmetry database

CrySymDB

English | 简体中文

CrySymDB is a Crystallographic Symmetry DataBase in Python.

• GitHub: CrySymDB | GitHub

---

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, spglib, and moyo APIs: for reading structure files and identifying their space-group and layer-group types.
• A Typer-based command line interface (CLI)

Classification levels for crystallographic groups

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:

python -m pip install "crysymdb[all]"

Minimal core packages only:

python -m pip install "crysymdb"

Core + CLI packages:

python -m pip install "crysymdb[cli]"

Quick Start

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:

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 directory includes pre-exported CSV and Excel tables that can be used directly without installing CrySymDB as a Python package:

• examples/csv: CSV files split by group family.
• 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: the same workbook with vertically repeated cells merged.

The directory also provides 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:

crysymdb --help

and for short:

csdb --help

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

csdb group plane p4mm
csdb group space 225

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

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

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:

cd path/to/CrySymDB

Install the package with the test dependencies:

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

Run the test suite:

python -m pytest

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

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.

Bug Reports & Feedback

If you encounter any bugs or have any feedback or suggestions,
please feel free to report them by opening an Issue.