Metadata-Version: 2.4
Name: findsym
Version: 0.1.0
Summary: FINDSYM: Symmetry detection for crystal structures
Home-page: https://github.com/AniruthAnanth/findsympy
Author: Aniruth Ananthanarayanan
Author-email: Aniruth Ananthanarayanan <aniruthananthanarayanan@my.unt.edu>
Maintainer-email: Aniruth Ananthanarayanan <aniruthananthanarayanan@my.unt.edu>
License: MIT
Project-URL: Homepage, https://github.com/AniruthAnanth/findsympy
Project-URL: Bug Reports, https://github.com/AniruthAnanth/findsympy/issues
Project-URL: Source, https://github.com/AniruthAnanth/findsympy
Keywords: crystallography,symmetry,spglib,materials-science
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.18.0
Requires-Dist: ase>=3.20.0
Requires-Dist: spglib>=1.16.0
Provides-Extra: visualization
Requires-Dist: matplotlib>=3.3.0; extra == "visualization"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: isort; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# FINDSYM: Crystal Structure Symmetry Detection

FINDSYM is a Python package for detecting and analyzing crystal structure symmetries. It provides tools to identify space groups, point groups, and Wyckoff positions in crystalline materials.

## Features

- **Space Group Detection**: Automatically identifies the space group of crystal structures
- **Point Group Analysis**: Determines the point group symmetries
- **Wyckoff Position Assignment**: Assigns atoms to their corresponding Wyckoff positions
- **Primitive Cell Finding**: Converts structures to their primitive cells
- **3D Visualization**: Interactive visualization of crystal structures (optional)
- **Multiple File Formats**: Supports CIF, POSCAR, XYZ, and other common structure formats

## Installation

### From PyPI (recommended)

```bash
pip install findsym
```

### With visualization support

```bash
pip install findsym[visualization]
```

### From source

```bash
git clone https://github.com/yourusername/findsym.git
cd findsym
pip install -e .
```

## Dependencies

- `numpy` >= 1.18.0
- `ase` >= 3.20.0 (Atomic Simulation Environment)
- `spglib` >= 1.16.0 (Space group library)
- `matplotlib` >= 3.3.0 (optional, for visualization)

## Quick Start

### Command Line Usage

```bash
# Basic symmetry analysis
findsym structure.cif

# With custom tolerance
findsym structure.cif --tolerance 1e-4

# With 3D visualization
findsym structure.cif --visualize
```

### Python API

```python
from findsym import findsym

# Analyze a crystal structure
result = findsym("SrTiO3.cif", tolerance=1e-3, visualize=True)

print(f"Space group number: {result['number']}")
print(f"Point group: {result['point group']}")
```

## Examples

### Analyzing SrTiO3

```python
import findsym

# Load and analyze SrTiO3 structure
result = findsym.findsym("SrTiO3_mp-4651_primitive.cif")

# Output will show:
# - Space group information
# - Standardized lattice parameters
# - Wyckoff positions for each atom
# - Symmetry operations
```

### Batch Processing

```python
import glob
from findsym import findsym

# Process multiple structures
for cif_file in glob.glob("*.cif"):
    print(f"Processing {cif_file}...")
    result = findsym(cif_file, tolerance=1e-3)
    print(f"Space group: {result['number']}")
```

## Output Information

FINDSYM provides detailed symmetry information including:

- **Space Group**: International symbol and number
- **Point Group**: Point group symbol
- **Lattice Parameters**: Standardized unit cell
- **Wyckoff Positions**: Site symmetries for each atom
- **Symmetry Operations**: Complete set of symmetry transformations
- **Equivalent Atoms**: Grouping of symmetrically equivalent atoms

## Supported File Formats

- CIF (Crystallographic Information File)
- POSCAR/CONTCAR (VASP)
- XYZ
- PDB
- And many others supported by ASE

## Visualization

When using the `--visualize` flag or `visualize=True` parameter, FINDSYM creates an interactive 3D plot showing:

- Crystal structure with atoms colored by element
- Unit cell boundaries
- Proper atomic radii
- Structure information overlay

## Advanced Usage

### Custom Tolerance

```python
# For high-precision structures
result = findsym("precise_structure.cif", tolerance=1e-5)

# For experimental/noisy data
result = findsym("experimental_structure.cif", tolerance=1e-2)
```

### Programmatic Access

```python
from findsym.core import (
    parse_input,
    find_primitive_cell,
    identify_point_group,
    match_to_standard_space_group
)

# Load structure
structure = parse_input("structure.cif")

# Find primitive cell
primitive = find_primitive_cell(structure)

# Get space group
dataset = match_to_standard_space_group(primitive, tolerance=1e-3)
print(f"Space group: {dataset['international']}")
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Citation

If you use FINDSYM in your research, please cite:

```
FINDSYM: Crystal Structure Symmetry Detection
https://github.com/yourusername/findsym
```

## Acknowledgments

- Inspired by the original [FINDSYM](https://stokes.byu.edu/iso/findsymform.php) from BYU's [Isotropy Software Suite](https://stokes.byu.edu/iso/isotropy.php)
- Built on top of [spglib](https://spglib.github.io/spglib/) for symmetry operations
- Uses [ASE](https://wiki.fysik.dtu.dk/ase/) for structure handling
- Visualization powered by [matplotlib](https://matplotlib.org/)

## Support

If you encounter any issues or have questions, please:

1. Check the [documentation](https://github.com/yourusername/findsym)
2. Search existing [issues](https://github.com/yourusername/findsym/issues)
3. Create a new issue if needed
