xyz-convert

A fast Rust implementation of XYZ file fixing and trajectory conversion utilities. This crate provides efficient tools for processing molecular dynamics trajectory files.

Features

• Fast XYZ file processing: Fix corrupted or malformed XYZ trajectory files
• Trajectory conversion: Convert between different trajectory formats with metadata
• Memory efficient: Streaming processing for large files
• Command-line tool: Single binary for XYZ processing and trajectory conversion

Installation

Rust Library

Add this to your Cargo.toml:

[dependencies]
xyz-convert = "0.1"

Build the binary:

cargo build --release

The executable will be available at target/release/xyz-convert

Usage

Convert to Trajectory

# Basic conversion
xyz-convert input.xyz reference.inp output.traj

# With additional options
xyz-convert input.xyz reference.inp output.traj \
    --index "0:1000" \
    --velocities velocities.xyz \
    --ener simulation.ener \
    --stress-folder stress_files/ \
    --wrap \
    --verbose

Fix XYZ Files

# Fix corrupted XYZ files during conversion
xyz-convert input.xyz reference.inp output.traj --fix

# With additional options
xyz-convert input.xyz reference.inp output.traj \
    --fix \
    --velocities velocities.xyz \
    --verbose

Rust Library

use xyz_convert::{fix_xyz_file, convert_to_trajectory};

// Fix XYZ file
fix_xyz_file("input.xyz", "output.traj", 1000)?;

// Convert to trajectory (from Rust code, you'd build the options differently)
convert_to_trajectory("pos.xyz", "reference.inp", "output.traj", None)?;

Functions

fix_xyz

Fixes corrupted XYZ files by:

• Detecting and interpolating missing frames
• Removing duplicate frames
• Memory-efficient processing of large files
• Automatic error recovery for common XYZ parsing issues

Parameters:

• input_path: Path to the input XYZ file
• output_path: Path for the fixed output file (any ASE-compatible format)
• trim_every: Number of images to process before trimming cache (default: 1000)

convert_to_traj

Converts XYZ files to trajectory format with additional metadata:

• Cell information from reference files
• Velocities from separate XYZ files
• Energies from .ener files
• Stress tensors from CP2K output files
• Atom wrapping to unit cell

Parameters:

• input_path: Path to the input XYZ file
• reference_path: Path to reference file for cell information
• output_path: Path for the output trajectory file
• options: Dictionary with optional parameters:
  • index: Index slice string (default: ":")
  • velocities_path: Path to velocities XYZ file
  • energy_path: Path to .ener file
  • stress_folder: Path to folder with stress tensor files
  • wrap_atoms: Whether to wrap atoms to unit cell (default: false)
  • verbose: Enable verbose output (default: false)

Performance

The Rust implementation provides significant performance improvements over the original Python version:

• Memory usage: Reduced memory footprint through streaming processing
• Speed: 5-10x faster processing for large trajectory files
• Scalability: Better handling of very large files (>GB)

Dependencies

This crate uses the fastatomstruct crate for efficient atomic structure I/O operations.

CI/CD Pipeline

This project includes a comprehensive GitLab CI/CD pipeline that:

• Runs tests and linting on every commit
• Builds and publishes documentation to GitLab Pages
• Creates cross-platform binary releases for tags
• Publishes to crates.io for tagged releases

For detailed information about the CI/CD setup, see docs/CI_CD.md.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT license.