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
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    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
~~~~~~~~~~~~~~~~~~~

.. code-block:: python

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

Saving a Trajectory
~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    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
~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

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

.. code-block:: rust

    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
~~~~~~~~~~~~~~~~~~~~

.. code-block:: rust

    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:

.. code-block:: bash

    # 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 :doc:`cli` documentation for complete CLI reference.

Compression Settings
~~~~~~~~~~~~~~~~~~~~

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

.. code-block:: python

    # 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