Material Science Descriptor Generator

A user-friendly GUI application for generating structure descriptors from VASP structure files. This tool provides an intuitive interface for creating SOAP, MBTR, and graph-based descriptors commonly used in material science and machine learning applications.

Screenshots

Main Interface

The main application window showing the configuration panel, dataset summary, and tabbed workspace

Descriptor Visualization

SOAP descriptor visualization for a single structure

3D Structure Viewer

Interactive 3D visualization of atomic structures with element-based coloring

MBTR K3 Grid

MBTR K3 angle descriptors showing all element angle combinations

MBTR K2 Grid

MBTR K2 distance descriptors showing all element distance combinations

Features

Descriptor Generation

• SOAP (Smooth Overlap of Atomic Positions) - Captures local atomic environments
• MBTR K2 (Many-Body Tensor Representation) - Distance-based descriptors
• MBTR K3 - Angle-based descriptors
• Graph Representations - Node and edge features with customizable cutoff distances

User Interface

• Drag-and-Drop Support - Drag files or folders directly into the application
• Automatic Element Detection - Automatically identifies elements from structure files
• Dynamic Parameters - Context-sensitive parameter controls based on selected descriptor type
• 3D Structure Viewer - Interactive visualization of atomic structures with customizable viewing angles
• Real-time Visualization - Plot descriptors as they are generated
• Multi-format Support - Handles both POSCAR and CONTCAR files

Installation

Prerequisites

• Python 3.8 or higher
• pip package manager

Dependencies

Install required packages using pip:

pip install -r requirements.txt

Required packages:

• numpy - Numerical computations
• matplotlib - Plotting and visualization
• ase - Atomic Simulation Environment
• dscribe - Descriptor generation library
• tkinter - GUI framework (usually included with Python)

Usage

Starting the Application

python3 descriptor_generator_gui.py

Workflow

1. Load Input

   • Drag & Drop: Drag a folder or CONTCAR/POSCAR file directly into the input field, OR
   • Manual Selection: Click "Browse..." to select a folder containing CONTCAR/POSCAR files, or select a single file
   • Click "Load Input" to scan and detect elements automatically
   • The application will display the number of structures found and detected elements

2. Configure Parameters

   • Select a descriptor type from the dropdown (SOAP, MBTR_k2, MBTR_k3, or Graph)
   • Adjust parameters for the selected descriptor type
   • Parameters update dynamically based on your selection

3. Generate Descriptors

   • Click "Generate Descriptors" to compute SOAP, MBTR K2, and MBTR K3 descriptors
   • Progress will be shown in the progress bar and console

4. Generate Graphs (Optional)

   • Select "Graph" descriptor type and set cutoff distance
   • Click "Generate Graphs" to create graph representations
   • Node and edge features will be computed based on atomic neighborhoods

5. Visualize Results

   • Use the "Descriptor Visualization" tab to plot descriptors for individual structures
   • Use the "3D Structure Viewer" tab to view atomic structures interactively
   • Adjust viewing angles with the azimuth and elevation sliders

File Structure

descriptors_visualization/
├── descriptor_generator_gui.py  # Main application with GUI
├── config.py                    # Configuration and element properties
├── utils.py                     # Utility functions for file I/O
├── requirements.txt             # Python dependencies
├── images/                      # Screenshot images for documentation
│   ├── main_interface_*.png
│   ├── descriptor_visualization_*.png
│   ├── structure_viewer_*.png
│   └── mbtr_grid_*.png
└── README.md                    # This file

Module Descriptions

descriptor_generator_gui.py

• Main application class DescriptorGeneratorApp
• GUI setup and event handlers
• Descriptor generation logic
• Visualization methods

config.py

• Default parameters for SOAP, MBTR, and graph generation
• Element color and size functions for visualization
• Atomic property mappings

utils.py

• find_files() - Recursive file search
• clean_vasp_symbols() - Handles VASP pseudopotential suffixes (e.g., Ba_sv → Ba)
• read_vasp_clean() - Wrapper for reading VASP files with automatic cleaning

Configuration

SOAP Parameters

• r_cut: Cutoff radius for local environments (default: 1.8 Å)
• n_max: Number of radial basis functions (default: 5)
• l_max: Maximum degree of spherical harmonics (default: 5)
• sigma: Width of Gaussian smearing (default: 0.25)
• rbf: Radial basis function type (gto or polynomial)
• average: Averaging mode (off, inner, or outer)

MBTR K2 Parameters

• Geometry: distance or inverse_distance
• g_min, g_max: Grid range
• g_n: Number of grid points (default: 100)
• g_sigma: Gaussian width
• r_cut: Cutoff radius (default: 8.0 Å)

MBTR K3 Parameters

• Geometry: cosine or angle
• g_min, g_max: Grid range
• g_n: Number of grid points (default: 100)
• g_sigma: Gaussian width
• r_cut: Cutoff radius (default: 8.0 Å)

Graph Parameters

• Cutoff Distance: Maximum distance for edge creation (default: 4.0 Å)
• Self Interaction: Include self-loops
• Both Ways: Create bidirectional edges

Tips and Best Practices

1. Large Datasets: For datasets with many structures, generation may take time. Monitor the console for progress updates.

2. Parameter Tuning:

   • MBTR parameters auto-adjust based on geometry selection
   • Start with default values and adjust based on your specific materials

3. Visualization Performance:

   • Very large structures (>500 atoms) are automatically limited for faster rendering
   • Descriptors with >2000 features are downsampled for plotting

4. Memory Management: The application automatically runs garbage collection to optimize memory usage.

Troubleshooting

Issue: VASP files not loading

• Solution: Ensure files are named CONTCAR or POSCAR
• The application automatically handles pseudopotential suffixes (e.g., Ba_sv, O_pv)

Issue: Import errors

• Solution: Verify all dependencies are installed with pip install -r requirements.txt

Issue: Slow visualization

• Solution: The application automatically optimizes rendering for large structures. Use lower grid point counts (g_n) for faster MBTR visualization.

Recent Updates

v1.0 - Code Cleanup (2026-01-16)

• Removed ~240 lines of unused code
• Optimized imports and reduced dependencies
• Improved code maintainability
• All functionality preserved

License

MIT License - Feel free to use and modify for your research and projects.

Citation

If you use this tool in your research, please cite the underlying libraries:

• DScribe: Himanen, L., et al. "DScribe: Library of descriptors for machine learning in materials science." Computer Physics Communications 247 (2020): 106949.
• ASE: Ask Hjorth Larsen, et al. "The atomic simulation environment—a Python library for working with atoms." Journal of Physics: Condensed Matter 29.27 (2017): 273002.

Contact

For questions, issues, or contributions, please open an issue on the project repository.

Acknowledgments

Built with:

• DScribe for descriptor generation
• ASE for atomic structure handling
• Matplotlib for visualization
• Tkinter for the GUI