Quickstart

This guide will help you get started with TACO Format quickly for both Python and Rust.

Python Quickstart

TACO Format provides a simple interface for working with molecular dynamics trajectories in Python, with ASE integration.

Saving a Single Structure

import ase
import taco_format

# Create or load an ASE Atoms object
atoms = ase.Atoms('H2O')

# Save to TACO format
taco_format.save_ase('water.taco', atoms)

Loading a Structure

# Load from TACO format
loaded_atoms = taco_format.load_ase('water.taco')

Saving a Trajectory

import ase
import taco_format

# Create or load a list of ASE Atoms objects
atoms_list = [ase.Atoms('H2O') for _ in range(10)]

# Save to TACO format with options
taco_format.write_frames('trajectory.taco', atoms_list,
                         time_step=0.001,  # Time step in ps
                         full_frame_interval=10,  # Frame interval for keyframes
                         compression_level=3)  # Compression level (1-22)

Loading a Trajectory

# Load entire trajectory
trajectory = taco_format.load_trajectory('trajectory.taco')

# Or load specific frames
frame_100 = taco_format.read('trajectory.taco', frame_index=100)

# Or load a range of frames
frames = taco_format.read_frame_range('trajectory.taco', 50, 150)

Rust Quickstart

TACO Format provides a native Rust API for high-performance trajectory reading and writing.

Writing a Trajectory

use taco_format::{Writer, Header, Frame, FrameData, CompressionSettings};
use ndarray::Array2;

// Create positions array (shape: [n_atoms, 3])
let positions = Array2::from_shape_fn((100, 3), |(i, j)| i as f32 + j as f32);

// Create frame data with positions
let frame_data = FrameData::new(positions);

// Create a frame
let frame = Frame::new(0, 0.0, frame_data);

// Create a writer with default settings
let mut writer = Writer::create("trajectory.taco").unwrap();

// Write frame
writer.write_frame(frame).unwrap();

// Finish writing
writer.finish().unwrap();

Reading a Trajectory

use taco_format::Reader;

// Open a trajectory file
let mut reader = Reader::open("trajectory.taco").unwrap();

// Get number of frames
let num_frames = reader.header().num_frames;
println!("Number of frames: {}", num_frames);

// Read a specific frame
let frame = reader.read_frame(0).unwrap();

// Access positions
if let Some(positions) = &frame.data.positions {
    println!("First atom position: {:?}", positions.row(0));
}

Advanced Options

Command Line Interface

TACO also provides a convenient command-line interface for common operations:

# Get file information
taco info trajectory.taco

# Extract specific frames
taco extract trajectory.taco subset.taco --start 100 --end 200

# Check file integrity
taco check trajectory.taco

# Show trajectory statistics
taco stats trajectory.taco

See the Command Line Interface documentation for complete CLI reference.

Compression Settings

TACO Format allows you to control the compression level and precision:

# For lossless compression (slower, larger files)
taco_format.write('trajectory.taco', atoms_list, lossless=True)

# For higher compression (faster reading, smaller files)
taco_format.write('trajectory.taco', atoms_list,
                  compression_level=10,  # Higher compression
                  full_frame_interval=50)  # Store full frame every 50 frames