Metadata-Version: 2.2
Name: mgtoolbox-kernel
Version: 0.1.3
Summary: MGToolBox Materials Genome Toolbox core library for crystal structure analysis
Home-page: https://gitee.com/shuhebing/mgtoolbox_kernel
Author: Bing He
Author-email: Bing He <shhebing@qq.com>
Project-URL: Homepage, https://gitee.com/shuhebing/mgtoolbox_kernel
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
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: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pycifrw
Requires-Dist: numpy>=1.20
Requires-Dist: scipy>=1.7
Requires-Dist: pandas>=1.3
Requires-Dist: spglib>=2.0
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# mgtoolbox-kernel

MGToolBox Materials Genome Toolbox core library for crystal structure analysis, CIF file processing, and computational materials science research.

## Installation

### Method 1: pip install

```bash
pip install mgtoolbox-kernel
```

### Method 2: Install from source

```bash
git clone https://gitee.com/shuhebing/mgtoolbox_kernel.git
cd mgtoolbox_kernel
pip install -e .
```

### Method 3: conda environment

```bash
conda install -c conda-forge spglib
pip install mgtoolbox-kernel
```

### Requirements

- Python >= 3.8
- numpy
- scipy
- pandas
- pycifrw
- spglib
- periodictable

## Usage

### 1. Reading Structure Files

Supports CIF and VASP POSCAR formats:

```python
from mgtoolbox_kernel.kernel import Structure, SymmetryStructure

# Read CIF file
structure = Structure.from_file("example.cif")

# Read POSCAR file
structure = Structure.from_file("POSCAR")

# Read structure with symmetry (supports magnetic moments)
sym_structure = SymmetryStructure.from_file("magnetic.cif")
```

**Output:**
```
结构类型: Structure
位点数量: 12

结构类型: Structure
位点数量: 6

结构类型: SymmetryStructure
位点数量: 2
空间群: Fm-3m
```

### 2. Reading from String Data

```python
from mgtoolbox_kernel.kernel import Structure, SymmetryStructure

# Read from CIF format string
cif_data = """
data_test
_cell_length_a    3.0
_cell_length_b    3.0
_cell_length_c    3.0
_cell_angle_alpha 90.0
_cell_angle_beta 90.0
_cell_angle_gamma 90.0
_symmetry_space_group_name_H-M 'P 1'
_symmetry_Int_Tables_number 1
loop_
_symmetry_equiv_pos_site_id
_symmetry_equiv_pos_as_xyz
1 'x, y, z'
loop_
_atom_site_label
_atom_site_type_symbol
_atom_site_fract_x
_atom_site_fract_y
_atom_site_fract_z
_atom_site_occupancy
Li1 Li 0.0 0.0 0.0 1.0
"""
structure = Structure.from_data(cif_data)

# Also supports SymmetryStructure
sym_structure = SymmetryStructure.from_data(cif_data)
```

**Output:**
```
结构类型: Structure
位点数量: 1
SymmetryStructure 位点数量: 1
空间群: Pm-3m
```

### 3. Creating Cells and Sites

```python
from mgtoolbox_kernel.kernel import Structure, SymmetryStructure, Cell, Site, Atom

# Create cell (a, b, c, alpha, beta, gamma)
cell = Cell.from_lattice_parameters(3.0, 3.0, 3.0, 90.0, 90.0, 90.0)

# Create sites
atom1 = Atom("Li", 1.0)
atom2 = Atom("O", -2.0)
site1 = Site([0.0, 0.0, 0.0], {atom1: 1.0}, label="Li1")
site2 = Site([0.5, 0.5, 0.5], {atom2: 1.0}, label="O1")

# Create structure
structure = Structure([site1, site2], cell)
```

**Output:**
```
晶胞类型: Cell
晶格参数: a=3.0, b=3.0, c=3.0
角度: alpha=90.0, beta=90.0, gamma=90.0

位点1:
{label:Li1, type:, coord:[0. 0. 0.], occupier:{[symbol_type:Li, valence:1.0]: 1.0}}
位点2:
{label:O1, type:, coord:[0.5 0.5 0.5], occupier:{[symbol_type:O, valence:-2.0]: 1.0}}

新结构位点数量: 2
```

### 4. Accessing Cell Information

```python
# Get lattice parameters
a, b, c = structure.cell.abc
alpha, beta, gamma = structure.cell.angles

# Get lattice basis vectors
lattice_vectors = structure.cell.cell_basis_vectors

# Get cell volume
volume = structure.cell.volume

# Get reciprocal lattice vectors
reciprocal_vectors = structure.cell.reciprocal_cell_vectors

# Get all lattice parameters as array
all_params = structure.cell.lattice_parameters  # [a, b, c, alpha, beta, gamma]
```

**Output:**
```
晶格参数 a, b, c: [4.61 4.61 4.61]
角度 alpha, beta, gamma: [90. 90. 90.]
晶格基矢:
[[4.61000000e+00 0.00000000e+00 0.00000000e+00]
 [2.82281087e-16 4.61000000e+00 0.00000000e+00]
 [2.82281087e-16 2.82281087e-16 4.61000000e+00]]
晶胞体积: 97.9722
倒易晶格向量:
[[ 2.16919740e-01 -1.32825032e-17 -1.32825032e-17]
 [ 1.32825032e-17  2.16919740e-01  7.64341756e-18]
 [ 1.32825032e-17  1.65432001e-17  2.16919740e-01]]
完整晶格参数: [ 4.61  4.61  4.61 90.   90.   90.  ]
```

### 5. Accessing Site Information

```python
# Iterate over all sites
for site in structure.sites:
    print(f"Site: {site.label}")
    print(f"Coordinate: {site.x}, {site.y}, {site.z}")
    print(f"Atom: {site.atom_symbols}")
    print(f"Occupancy: {site.atom_occupancies}")

# Check if structure is ordered
is_ordered = structure.is_ordered
```

**Output:**
```
位点: Li1_0
  坐标: 0.5000, 0.5000, 0.5000
  原子: ['Li']
  占据率: [1.0]
位点: Li2_0
  坐标: 0.0000, 0.0000, 0.5000
  原子: ['Li']
  占据率: [1.0]

结构是否有序: True

Li1_0 是否有序: True
Li2_0 是否有序: True
```

### 6. Atom Operations

```python
# Add site
new_atom = Atom("Fe", 3.0)
new_site = Site([0.25, 0.25, 0.25], {new_atom: 1.0}, label="Fe1")
structure.add_site(new_site)
print(f"添加后位点数量: {len(structure.sites)}")

# Add multiple sites
structure.add_sites([site1, site2])

# Remove sites
structure.remove_sites([new_site])
print(f"删除后位点数量: {len(structure.sites)}")

# Update cell
structure.set_cell(new_cell)
```

**Output:**
```
添加后位点数量: 13
删除后位点数量: 12
```

### 7. Calculating Interatomic Distances

```python
import numpy as np

# Calculate minimum image distance between two sites
distance = structure.get_mic_dis([0.0, 0.0, 0.0], [0.5, 0.5, 0.5])
print(f"距离: {distance:.4f}")

# Use Cell class to calculate distances between Cartesian coordinates
cart_coords1 = np.array([[0.0, 0.0, 0.0], [1.0, 1.0, 1.0]])
cart_coords2 = np.array([[0.5, 0.5, 0.5], [2.0, 2.0, 2.0]])
distance_vectors, lengths = structure.cell.get_distances(cart_coords1, cart_coords2)

# Calculate minimum image distance between two points
vector, length = structure.cell.distance([0.0, 0.0, 0.0], [2.5, 2.5, 2.5])
```

**Output:**
```
距离: 3.9924

距离向量:
[[[ 0.5  0.5  0.5]
  [ 2.   2.   2. ]]
 [[-0.5 -0.5 -0.5]
  [ 1.   1.   1. ]]]
距离长度: [[0.8660254  3.46410162]
 [0.8660254  1.73205081]]

距离向量: [-2.11 -2.11 -2.11]
距离长度: 3.6546
```

### 8. Coordinate Transformation

```python
# Fractional to Cartesian
cart_coords = structure.cell.get_cartesian_coords([0.5, 0.5, 0.5])

# Cartesian to Fractional
frac_coords = structure.cell.get_fractional_coordinates([1.5, 1.5, 1.5])
```

**Output:**
```
分数坐标: [0.5, 0.5, 0.5]
笛卡尔坐标: [2.305 2.305 2.305]

笛卡尔坐标: [1.5, 1.5, 1.5]
分数坐标: [0.32537961 0.32537961 0.32537961]
```

### 9. Cell Reduction

```python
# Niggli reduction
reduced_cell = structure.cell.get_reduced_cell(algorithm='niggli')
print(f"Reduced lattice parameters: {reduced_cell.abc}")
```

**Output:**
```
原晶格参数: [4.61 4.61 4.61]
约化后晶格参数: [4.61 4.61 4.61]
```

### 10. Writing Structure Files

```python
# Write CIF file
structure.write_to_cif("output.cif")

# Write VASP POSCAR file (ordered structures only)
sym_structure.write_to_poscar("POSCAR", scale=1.0)
```

**Output:**
```
已写入 test_output.cif
已写入 test_output.vasp
```

### 11. Getting Symmetry Information

```python
# Get space group information
space_group = sym_structure.space_group_info
print(f"Space group number: {space_group['space_group_number']}")
print(f"Space group name: {space_group['space_group_name']}")
print(f"Hall number: {space_group['space_group_hall_number']}")
print(f"Equivalent atoms: {space_group['equivalent_atoms']}")
```

**Output:**
```
空间群编号: 225
空间群名称: Fm-3m
Hall 编号: 523
等价原子索引: [0 0 0 0 0 0 0 0 8 8...]
```

## Running Tests

```bash
# Install dev dependencies
pip install pytest

# Run all tests
pytest tests/

# Run specific test files
pytest tests/test_kernel.py
pytest tests/test_structure_is_ordered.py
pytest tests/test_cif_esd.py
```

## Module Structure

| Module | Description |
|--------|-------------|
| `mgtoolbox_kernel.io` | File I/O (CIF, VASP POSCAR) |
| `mgtoolbox_kernel.kernel` | Core data models (Structure, SymmetryStructure, Cell, Site, Atom) |
| `mgtoolbox_kernel.util` | Utility functions (symmetry parsing, lattice vector conversion) |
| `mgtoolbox_kernel.crystal_tools` | Crystal symmetry analysis tools (based on spglib) |


