mgtoolbox-kernel 0.1.3

MGToolBox Materials Genome Toolbox core library for crystal structure analysis

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

pip install mgtoolbox-kernel

Method 2: Install from source

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

Method 3: conda environment

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:

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

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

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

# 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

# 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

# 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

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

# 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

# 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

# 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

# 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

# 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)