### Calculate RMSD on Cloud Trajectory with MDAnalysis

Source: https://github.com/becksteinlab/zarrtraj/blob/main/joss_paper/paper.md

This example shows how to perform Root Mean Square Deviation (RMSD) analysis on a cloud-hosted trajectory loaded with MDAnalysis. It selects the C-alpha atoms of the protein and uses the MDAnalysis.analysis.rms.RMSD class to compute RMSD after optimal structural superposition. The analysis is run with a step of 100 frames, and the initial and final RMSD values are printed.

```python
import MDAnalysis.analysis.rms
R = MDAnalysis.analysis.rms.RMSD(u, select="protein and name CA").run(
                                     step=100, verbose=True)
print(f"Initial RMSD (frame={R.results.rmsd[0, 0]:g}): "
          f"{R.results.rmsd[0, 2]:.3f} Å")
print(f"Final RMSD (frame={R.results.rmsd[-1, 0]:g}): "
          f"{R.results.rmsd[-1, 2]:.3f} Å")
```

--------------------------------

### Import Zarrtraj and MDAnalysis for Trajectory Loading

Source: https://github.com/becksteinlab/zarrtraj/blob/main/joss_paper/paper.md

This snippet demonstrates how to import the Zarrtraj and MDAnalysis libraries to load trajectory data directly from an S3 URL. It assumes the necessary libraries are installed and S3 credentials are configured.

```python
import zarrtraj
import MDAnalysis as mda

u = mda.Universe("topology.pdb", "s3://sample-bucket-name/trajectory.h5md")
```

--------------------------------

### Get Auxiliary Descriptions (Python)

Source: https://github.com/becksteinlab/zarrtraj/blob/main/docs/source/api.md

Retrieves descriptions for specified auxiliary data sources, or all if none are specified. These descriptions can be used to recreate the auxiliaries later, for example, to duplicate them into another trajectory.

```python
def get_aux_descriptions(auxnames=None):
    """Get descriptions to allow reloading the specified auxiliaries.

    If no auxnames are provided, defaults to the full list of added auxiliaries.
    """
    pass
```

--------------------------------

### Stream YiiP Protein Trajectory from Cloud Storage (Python)

Source: https://github.com/becksteinlab/zarrtraj/blob/main/docs/source/yiip_example.md

This snippet shows how to load and iterate over a protein trajectory stored in ZarrMD format on Google Cloud Storage using zarrtraj and MDAnalysis. It requires the zarrtraj and MDAnalysis libraries, and fsspec for cloud access. The input is a PDB topology file and a ZarrMD trajectory file, and the output is frame information and the protein's center of mass for selected frames.

```python
import zarrtraj
import MDAnalysis as mda
import fsspec

with fsspec.open("gcs://zarrtraj-test-data/YiiP_system.pdb", "r") as top:

    u = mda.Universe(
        top, "gcs://zarrtraj-test-data/yiip.zarrmd", topology_format="PDB"
    )
    protein = u.select_atoms("protein")

    for ts in u.trajectory[::100]:
        print(f"{ts.frame}, {ts.time}, {protein.center_of_mass()}")
```

--------------------------------

### Load Disk Trajectory Data with MDAnalysis

Source: https://github.com/becksteinlab/zarrtraj/blob/main/joss_paper/figure_2.ipynb

Loads trajectory data from local disk files (PDB, H5MD, ZarrMD, XTC) into MDAnalysis Universe objects. This setup is necessary for performing subsequent benchmark tests on disk-based data.

```python
import MDAnalysis as mda
import zarrtraj

TOPOL = "../zarrtraj/data/yiip_equilibrium/YiiP_system.pdb"
H5MD_DISK_TRAJ = "../zarrtraj/data/yiip_aligned_compressed.h5md"
ZARRMD_TRAJ_DISK = "../zarrtraj/data/yiip_aligned_compressed.zarrmd"
XTC_TRAJ = "../zarrtraj/data/yiip_equilibrium/YiiP_system_90ns_center_aligned.xtc"

xtc_u = mda.Universe(TOPOL, XTC_TRAJ)
h5md_disk_u = mda.Universe(TOPOL, H5MD_DISK_TRAJ)
zarrmd_disk_u = mda.Universe(TOPOL, ZARRMD_TRAJ_DISK)
```

--------------------------------

### Read AWS S3 Trajectories with Zarrtraj

Source: https://context7.com/becksteinlab/zarrtraj/llms.txt

Shows how to stream molecular dynamics trajectories directly from AWS S3 buckets using MDAnalysis and zarrtraj. It covers configuring AWS credentials and loading both .h5md and .zarrmd files, including examples of analysis and authenticated access.

```python
import zarrtraj
import MDAnalysis as mda
import os

# Configure AWS credentials
os.environ["AWS_PROFILE"] = "my_aws_profile"
os.environ["AWS_REGION"] = "us-west-1"

# Load trajectory from S3 - works with both .h5md and .zarrmd files
u = mda.Universe(
    "topology.tpr",
    "s3://my-bucket/trajectories/simulation.h5md"
)

# Perform analysis on cloud-stored trajectory
protein = u.select_atoms("protein")
for ts in u.trajectory[::100]:  # Every 100th frame
    com = protein.center_of_mass()
    print(f"Frame {ts.frame}, Time {ts.time}, COM: {com}")

# Access with custom storage options
u = mda.Universe(
    "topology.tpr",
    "s3://my-bucket/simulation.zarrmd",
    storage_options={"anon": False}  # For authenticated access
)
```

--------------------------------

### Read H5MD/Zarrmd file from S3 using Python and MDAnalysis

Source: https://github.com/becksteinlab/zarrtraj/blob/main/docs/source/walkthrough.md

This Python script demonstrates how to read an H5MD or Zarrmd file directly from an S3 bucket using MDAnalysis. It sets up AWS credentials via environment variables and then initializes an MDAnalysis Universe object with the S3 path. The example then selects protein atoms and iterates through trajectory frames, printing frame information and protein center of mass.

```python
import zarrtraj
import MDAnalysis as mda
import MDAnalysisData
import os

os.environ["AWS_PROFILE"] = "sample_profile"
os.environ["AWS_REGION"] = "us-west-1"

dataset = MDAnalysisData.yiip_equilibrium.fetch_yiip_equilibrium_short()
# here, we show the .zarrmd file being read, but the .h5md file could be read identically
u = mda.Universe(dataset.topology, "s3://sample-bucket-name/YiiP_system_9ns_center.zarrmd")
protein = u.select_atoms("protein")
for ts in u.trajectory[::100]:
    print(f"{ts.frame}, {ts.time}, {protein.center_of_mass()}")
```

--------------------------------

### Load Cloud Trajectory and Topology with MDAnalysis

Source: https://github.com/becksteinlab/zarrtraj/blob/main/joss_paper/paper.md

This code snippet demonstrates how to load a PDB topology file and a Zarr trajectory file from Google Cloud Storage using fsspec and MDAnalysis. It opens the topology file, creates an MDAnalysis Universe object, and iterates through a slice of the trajectory, printing each timestep. This showcases the integration of cloud storage with standard MDAnalysis workflows.

```python
import zarrtraj
import MDAnalysis as mda
import fsspec

with fsspec.open("gcs://zarrtraj-test-data/YiiP_system.pdb", "r") as top:
    u = mda.Universe(top, "gcs://zarrtraj-test-data/yiip.zarrmd", 
	                 topology_format="PDB")

    for timestep in u.trajectory[100::20]:
        print(timestep)
```

--------------------------------

### Loading .h5md and .zarrmd files from disk

Source: https://github.com/becksteinlab/zarrtraj/blob/main/docs/source/api.md

Demonstrates how to load simulation data from local .h5md or .zarrmd trajectory files using MDAnalysis.Universe.

```APIDOC
## Loading .h5md and .zarrmd files from disk

### Description
Load a simulation from a `.h5md` or `.zarrmd` trajectory file by providing the topology file and the path to the trajectory file to the `MDAnalysis.core.universe.Universe` constructor.

### Method
```python
import zarrtraj
import MDAnalysis as mda

u = mda.Universe("topology.tpr", "trajectory.h5md")
# or
u = mda.Universe("topology.tpr", "trajectory.zarrmd")
```

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import zarrtraj
import MDAnalysis as mda

u = mda.Universe("topology.tpr", "trajectory.h5md")
```

### Response
#### Success Response (200)
An `MDAnalysis.core.universe.Universe` object is returned, loaded with the simulation data.

#### Response Example
```python
# No direct response example, but the Universe object can be used like:
# print(u.trajectory[0])
```
```

--------------------------------

### Get Auxiliary Attribute Value (Python)

Source: https://github.com/becksteinlab/zarrtraj/blob/main/docs/source/api.md

Retrieves the value of a specific attribute from an auxiliary data source. This function requires the name of the auxiliary and the name of the attribute to fetch.

```python
def get_aux_attribute(auxname, attrname):
    """Get the value of *attrname* from the auxiliary *auxname*."""
    pass
```

--------------------------------

### Fetch Sample Trajectory Data with MDAnalysisData

Source: https://github.com/becksteinlab/zarrtraj/blob/main/joss_paper/figure_1.ipynb

This Python snippet demonstrates how to download sample PDB topology and XTC trajectory files using the MDAnalysisData library. These files are essential for reproducing the stride benchmark analysis.

```python
import MDAnalysisData

dataset = MDAnalysisData.yiip_equilibrium.fetch_yiip_equilibrium_long(data_home="../zarrtraj/data")
```

--------------------------------

### Handling Multiple Particle Groups in H5MD with Zarrtraj

Source: https://context7.com/becksteinlab/zarrtraj/llms.txt

Illustrates how to work with H5MD files that contain multiple particle groups using zarrtraj and MDAnalysis. It shows how to specify the desired particle group by name when initializing the Universe.

```python
import zarrtraj
import MDAnalysis as mda

# If H5MD file contains multiple groups in 'particles', specify which one
u = mda.Universe(
    "topology.pdb",
    "multi_group_simulation.h5md",
    group="protein_atoms"  # Specify the particle group name
)

# If only one group exists, it's selected automatically
u = mda.Universe("topology.pdb", "single_group.h5md")

# Access trajectory properties
print(f"Reading from group with {u.trajectory.n_atoms} atoms")
print(f"Trajectory has {u.trajectory.n_frames} frames")
print(f"Time unit: {u.trajectory.units['time']}")
print(f"Length unit: {u.trajectory.units['length']}")
```

--------------------------------

### Check and Clip Slice Indices for Trajectories (Python)

Source: https://github.com/becksteinlab/zarrtraj/blob/main/docs/source/api.md

Validates and adjusts trajectory frame indices (start, stop, step) to fit within the trajectory's bounds. It follows standard Python range() conventions but has a warning regarding its use with slice() when stop is None and step is -1, which can lead to unexpected empty slices.

```python
def check_slice_indices(start, stop, step):
    """Check frame indices are valid and clip to fit trajectory.

    The usage follows standard Python conventions for `range()` but see
    the warning below.

    * **Parameters:**
      * **start** (*int or None*) – Starting frame index (inclusive). `None` corresponds to the default
        of 0, i.e., the initial frame.
      * **stop** (*int or None*) – Last frame index (exclusive). `None` corresponds to the default
        of n_frames, i.e., it includes the last frame of the trajectory.
      * **step** (*int or None*) – step size of the slice, `None` corresponds to the default of 1, i.e, 
        include every frame in the range start, stop.
    * **Returns:**
      **start, stop, step** – Integers representing the slice
    * **Return type:**
      [tuple](https://docs.python.org/3/library/stdtypes.html#tuple) ([int](https://docs.python.org/3/library/functions.html#int), [int](https://docs.python.org/3/library/functions.html#int), [int](https://docs.python.org/3/library/functions.html#int))
    """
    # Implementation details would go here
    pass
```

--------------------------------

### Optimized Trajectory Writing with Zarrtraj

Source: https://context7.com/becksteinlab/zarrtraj/llms.txt

Shows how to configure optimized settings for writing trajectories with zarrtraj and MDAnalysis. This includes setting compression, precision, pre-allocating frames, and specifying data to write (positions, velocities, forces) for better file size and performance.

```python
import zarrtraj
import MDAnalysis as mda
import numcodecs
from MDAnalysisTests.datafiles import PSF, DCD

u = mda.Universe(PSF, DCD)

# Optimized writer configuration
with mda.Writer(
    "optimized.zarrmd",
    n_atoms=u.atoms.n_atoms,
    # Pre-allocate for known frame count (improves performance)
    n_frames=u.trajectory.n_frames,
    # Reduce precision to 3 decimal places (similar to XTC)
    precision=3,
    # Use zstd compression for best ratio
    compressor=numcodecs.Blosc(cname="zstd", clevel=9),
    # Control what data to write
    positions=True,
    velocities=False,  # Skip velocities if not needed
    forces=False,      # Skip forces if not needed
    # Custom units
    timeunit="ps",
    lengthunit="Angstrom",
    # Metadata
    author="Researcher Name",
    author_email="researcher@example.com",
) as W:
    for ts in u.trajectory:
        W.write(u.atoms)

print(f"Wrote {u.trajectory.n_frames} frames")
```

--------------------------------

### Read Google Cloud Storage Trajectories with Zarrtraj

Source: https://context7.com/becksteinlab/zarrtraj/llms.txt

Illustrates streaming trajectories from Google Cloud Storage (GCS) buckets using MDAnalysis and zarrtraj. It demonstrates loading trajectories when the topology file is also in GCS (using fsspec) and when the topology is local.

```python
import zarrtraj
import MDAnalysis as mda
import fsspec

# For topology files in GCS, use fsspec to create a file-like object
with fsspec.open("gcs://my-bucket/YiiP_system.pdb", "r") as top:
    u = mda.Universe(
        top,
        "gcs://my-bucket/trajectory.zarrmd",
        topology_format="PDB"
    )

    # Analyze the trajectory
    protein = u.select_atoms("protein")
    for ts in u.trajectory[::100]:
        print(f"{ts.frame}, {ts.time}, {protein.center_of_mass()}")

# Direct loading if topology is local
u = mda.Universe(
    "local_topology.pdb",
    "gcs://my-bucket/trajectory.h5md"
)
```

--------------------------------

### Write trajectory to AWS S3 in .zarrmd format

Source: https://github.com/becksteinlab/zarrtraj/blob/main/docs/source/api.md

Writes simulation trajectory data directly to an AWS S3 bucket in the .zarrmd format. This example demonstrates writing a DCD trajectory to an S3 path. Authentication is handled via AWS profile environment variables. The writer uses a default chunking strategy of ~12MB per chunk.

```python
import zarrtraj
import MDAnalysis as mda
from MDAnalysisTests.datafiles import PSF, DCD
import os

os.environ["AWS_PROFILE"] = "sample_profile"
os.environ["AWS_REGION"] = "us-west-1"

u = mda.Universe(PSF, DCD)
with mda.Writer("s3://sample-bucket/trajectory.zarrmd",
                n_atoms=u.atoms.n_atoms) as w:
    for ts in u.trajectory:
        w.write(u.atoms)
```

--------------------------------

### Basic Trajectory Writing with MDAnalysis

Source: https://context7.com/becksteinlab/zarrtraj/llms.txt

Demonstrates how to write all frames of a trajectory to a Zarr-MD (zarrmd) file using MDAnalysis. It covers writing the entire trajectory, writing specific selections of atoms, and writing every Nth frame.

```python
import MDAnalysis as mda

# Writes all frames
with mda.Writer("output.zarrmd", n_atoms=u.atoms.n_atoms) as W:
    for ts in u.trajectory:
        W.write(u.atoms)

# Write specific selections
protein = u.select_atoms("protein")
with mda.Writer("protein_only.zarrmd", n_atoms=protein.n_atoms) as W:
    for ts in u.trajectory:
        W.write(protein)

# Write every 10th frame
with mda.Writer("sparse.zarrmd", n_atoms=u.atoms.n_atoms) as W:
    for ts in u.trajectory[::10]:
        W.write(u.atoms)
```

--------------------------------

### Write Local Trajectories with Zarrtraj

Source: https://context7.com/becksteinlab/zarrtraj/llms.txt

Demonstrates writing molecular dynamics trajectories in the ZarrMD format to local files using the ZARRMDWriter class from zarrtraj. It emphasizes the use of the context manager pattern for proper file handling.

```python
import zarrtraj
import MDAnalysis as mda
from MDAnalysisTests.datafiles import PSF, DCD

# Load source trajectory
u = mda.Universe(PSF, DCD)

# Example of writing (actual writer code would follow)
# with zarrtraj.ZARRMDWriter("output.zarrmd") as writer:
#     for ts in u.trajectory:
#         writer.write(ts)
```

--------------------------------

### Configuring Reader Cache Size for Zarrtraj

Source: https://context7.com/becksteinlab/zarrtraj/llms.txt

Explains how to configure the reader cache size for optimizing remote file access performance when using zarrtraj with MDAnalysis. It shows how to set the cache size in bytes and discusses the impact on random access performance.

```python
import zarrtraj
import MDAnalysis as mda
import os

os.environ["AWS_PROFILE"] = "my_profile"
os.environ["AWS_REGION"] = "us-west-1"

# Configure cache size (default is 100MB)
# Larger cache = better performance for random access
# Smaller cache = lower memory usage
u = mda.Universe(
    "topology.tpr",
    "s3://my-bucket/large_trajectory.zarrmd",
    cache_size=200 * 1024 * 1024,  # 200 MB cache
)

# Sequential iteration is optimized automatically
for ts in u.trajectory:
    # Process frame
    pass

# Random access benefits from larger cache
import random
frames = random.sample(range(u.trajectory.n_frames), 100)
for frame in frames:
    u.trajectory[frame]
    # Process frame
```

--------------------------------

### Run Disk Trajectory Stride Benchmarks

Source: https://github.com/becksteinlab/zarrtraj/blob/main/joss_paper/figure_1.ipynb

This Python script executes the stride benchmark on trajectory data stored on disk (XTC, H5MD, ZarrMD). It uses the `time_stride` function to measure and print the iteration time for each format.

```python
xtc_stride_time = time_stride(xtc_u.trajectory)
print(f"XTC stride time: {xtc_stride_time:.2f} seconds")
h5md_disk_stride_time = time_stride(h5md_disk_u.trajectory)
print(f"H5MD on disk stride time: {h5md_disk_stride_time:.2f} seconds")
zarrmd_disk_stride_time = time_stride(zarrmd_disk_u.trajectory)
print(f"ZarrMD on disk stride time: {zarrmd_disk_stride_time:.2f} seconds")
```

--------------------------------

### Load Disk Trajectory Data for Benchmarking

Source: https://github.com/becksteinlab/zarrtraj/blob/main/joss_paper/figure_1.ipynb

This Python code loads trajectory data from disk in H5MD, ZarrMD, and XTC formats using MDAnalysis and zarrtraj. It prepares Universe objects for subsequent stride benchmarking.

```python
import MDAnalysis as mda
import zarrtraj

TOPOL = "../zarrtraj/data/yiip_equilibrium/YiiP_system.pdb"
H5MD_DISK_TRAJ = "../zarrtraj/data/yiip_aligned_uncompressed.h5md"
ZARRMD_TRAJ_DISK = "../zarrtraj/data/yiip_aligned_uncompressed.zarrmd"
XTC_TRAJ = "../zarrtraj/data/yiip_equilibrium/YiiP_system_90ns_center_aligned.xtc"

xtc_u = mda.Universe(TOPOL, XTC_TRAJ)
h5md_disk_u = mda.Universe(TOPOL, H5MD_DISK_TRAJ)
zarrmd_disk_u = mda.Universe(TOPOL, ZARRMD_TRAJ_DISK)
```

--------------------------------

### Load Topology with fsspec

Source: https://github.com/becksteinlab/zarrtraj/blob/main/examples/rmsd_yiip.ipynb

Loads a PDB topology file from a Google Cloud Storage (GCS) bucket into memory using the `fsspec` library. This prepares the topology for use with MDAnalysis.

```python
import fsspec
from io import StringIO

with fsspec.open("gcs://zarrtraj-test-data/YiiP_system.pdb", "r") as f:
    yiip_topology = StringIO(f.read())
```

--------------------------------

### Read Local Trajectories with Zarrtraj

Source: https://context7.com/becksteinlab/zarrtraj/llms.txt

Demonstrates how to load H5MD and ZarrMD trajectory files from local disk using MDAnalysis after importing zarrtraj. It covers iterating through frames, accessing specific frames, and retrieving trajectory properties.

```python
import zarrtraj
import MDAnalysis as mda

# Load a local .h5md trajectory file
u = mda.Universe("topology.tpr", "trajectory.h5md")

# Or load a local .zarrmd trajectory file
u = mda.Universe("topology.pdb", "simulation.zarrmd")

# Iterate through frames
for ts in u.trajectory:
    print(f"Frame {ts.frame}: Time {ts.time} ps")
    print(f"Positions shape: {ts.positions.shape}")

# Access specific frames
u.trajectory[0]  # First frame
u.trajectory[-1]  # Last frame
u.trajectory[::10]  # Every 10th frame

# Get trajectory properties
print(f"Number of frames: {u.trajectory.n_frames}")
print(f"Number of atoms: {u.trajectory.n_atoms}")
print(f"Total time: {u.trajectory.totaltime} ps")
```

--------------------------------

### Writing Trajectories Directly to AWS S3 with Zarrtraj

Source: https://context7.com/becksteinlab/zarrtraj/llms.txt

Demonstrates how to write trajectory data directly to AWS S3 using MDAnalysis and zarrtraj, avoiding local intermediate files. It includes configuration for AWS credentials and shows how to use the 's3://' protocol.

```python
import zarrtraj
import MDAnalysis as mda
import MDAnalysisData
import numcodecs
import os

# Configure AWS credentials
os.environ["AWS_PROFILE"] = "my_aws_profile"
os.environ["AWS_REGION"] = "us-west-1"

# Load source data
dataset = MDAnalysisData.yiip_equilibrium.fetch_yiip_equilibrium_short()
u = mda.Universe(dataset.topology, dataset.trajectory)

# Write directly to S3
with mda.Writer(
    "s3://my-bucket/trajectories/YiiP_simulation.zarrmd",
    n_atoms=u.atoms.n_atoms,
    n_frames=u.trajectory.n_frames,
    precision=3,
    compressor=numcodecs.Blosc(cname="zstd", clevel=9),
) as W:
    for ts in u.trajectory:
        W.write(u.atoms)

# For Google Cloud Storage, use gcs:// protocol
# For Azure, use az://, abfs://, or adl:// protocols
```

--------------------------------

### Generate ASV Benchmark Figure with Matplotlib

Source: https://github.com/becksteinlab/zarrtraj/blob/main/joss_paper/figure_1.ipynb

This Python script uses Matplotlib to generate a bar chart comparing the iteration speed of different trajectory file formats and storage mediums. It visualizes benchmark results, showing time in minutes for each configuration.

```python
import matplotlib.pyplot as plt


labels = ['SSD, XTC', 'SSD, H5MD',  'AWS S3, H5MD', 'SSD, ZarrMD', 'AWS S3, ZarrMD']
values = [1.49, 4.76, 10.30,3.10, 6.53]  
colors = ['#009e73', '#e69f00', '#e69f00','#56b4e9', '#56b4e9']

plt.figure(figsize=(8, 6))
plt.bar(labels, values, color=colors)


plt.title('Comparison of Trajectory Iteration Speed by Storage Medium')
plt.ylabel('Time (minutes)')


plt.xticks(rotation=45, ha='right')
plt.tight_layout()

plt.savefig('benchmark.png')
plt.show()
```

--------------------------------

### Convert Trajectories to ZarrMD Format with Python

Source: https://context7.com/becksteinlab/zarrtraj/llms.txt

Illustrates how to convert trajectories from any format supported by MDAnalysis into the cloud-optimized ZarrMD format using zarrtraj. It allows for specifying compression and data inclusion (positions, velocities, forces).

```python
import zarrtraj
import MDAnalysis as mda
import numcodecs

# Load trajectory in any format supported by MDAnalysis
u = mda.Universe("system.tpr", "trajectory.xtc")

# Convert to ZarrMD with optimized settings
with mda.Writer(
    "converted.zarrmd",
    n_atoms=u.atoms.n_atoms,
    n_frames=u.trajectory.n_frames,
    precision=3,
    compressor=numcodecs.Blosc(cname="zstd", clevel=9),
    positions=True,
    velocities=u.trajectory.ts.has_velocities,
    forces=u.trajectory.ts.has_forces,
) as W:
    for ts in u.trajectory:
        W.write(u.atoms)

# Verify the conversion
u_zarrmd = mda.Universe("system.tpr", "converted.zarrmd")
print(f"Original frames: {u.trajectory.n_frames}")
print(f"Converted frames: {u_zarrmd.trajectory.n_frames}")
```

--------------------------------

### Write and Upload Simulation Trajectory to H5MD and S3

Source: https://github.com/becksteinlab/zarrtraj/blob/main/docs/source/walkthrough.md

This Python script demonstrates writing a molecular dynamics trajectory to an H5MD file using MDAnalysis and then uploading it to AWS S3. It fetches a sample trajectory, writes it to 'YiiP_system_9ns_center.h5md', and then calls a function to upload it. It also shows how to set AWS region environment variable.

```python
import MDAnalysis as mda
import MDAnalysisData
import os

# This is the AWS region where the bucket is located
os.environ["AWS_REGION"] = "us-west-1"

def upload_h5md_file(bucket_name, file_name):
    s3_client = boto3.client("s3")
    obj_name = os.path.basename(file_name)

    response = s3_client.upload_file(file_name, bucket_name, obj_name)

if __name__ == "__main__":
    dataset = MDAnalysisData.yiip_equilibrium.fetch_yiip_equilibrium_short()

    u = mda.Universe(dataset.topology, dataset.trajectory)

    with mda.Writer(
        "YiiP_system_9ns_center.h5md",
        n_atoms=u.atoms.n_atoms,
        # (111815 atoms * 4 bytes per float * 3 (xyz)) = ~1.34 MB per frame
        # 8 frames per chunk to reach goal of 8-12 MB per chunk
        chunks=(8, u.atoms.n_atoms, 3),
    ) as W:
        for ts in u.trajectory:
            W.write(u.atoms)

    upload_h5md_file(
        "sample-bucket-name",
        "YiiP_system_9ns_center.h5md",
    )
```

--------------------------------

### Read Azure Storage Trajectories with Zarrtraj

Source: https://context7.com/becksteinlab/zarrtraj/llms.txt

Explains how to stream trajectories from Azure Blob Storage or Azure Data Lakes using MDAnalysis and zarrtraj. It covers authentication via connection strings and loading files using the 'az://' and 'abfs://' protocols.

```python
import zarrtraj
import MDAnalysis as mda
import os

# Configure Azure credentials via connection string
os.environ["AZURE_STORAGE_CONNECTION_STRING"] = (
    "DefaultEndpointsProtocol=https;AccountName=myaccount;"
    "AccountKey=mykey;EndpointSuffix=core.windows.net"
)

# Load from Azure Blob Storage (az:// protocol)
u = mda.Universe(
    "topology.tpr",
    "az://my-container/simulation.h5md"
)

# Alternative protocols: abfs:// or adl:// for Data Lakes
u = mda.Universe(
    "topology.pdb",
    "abfs://my-container/simulation.zarrmd"
)

# Iterate and analyze
for ts in u.trajectory:
    print(f"Frame {ts.frame}: {ts.positions.mean(axis=0)}")
```

--------------------------------

### Run RMSD Analysis on Cloud Trajectories with Python

Source: https://context7.com/becksteinlab/zarrtraj/llms.txt

Shows how to perform standard MDAnalysis analyses, specifically RMSD calculation, on trajectories stored in the cloud using zarrtraj. It leverages fsspec for cloud storage access and MDAnalysis for the analysis.

```python
import zarrtraj
import MDAnalysis as mda
from MDAnalysis.analysis import rms
import fsspec

# Load trajectory from cloud
with fsspec.open("gcs://zarrtraj-test-data/YiiP_system.pdb", "r") as top:
    u = mda.Universe(
        top,
        "gcs://zarrtraj-test-data/yiip.zarrmd",
        topology_format="PDB"
    )

    # Select atoms for RMSD calculation
    protein_ca = u.select_atoms("protein and name CA")

    # Run RMSD analysis
    R = rms.RMSD(
        protein_ca,
        protein_ca,
        select="protein and name CA",
        ref_frame=0
    )
    R.run()

    # Access results
    print(f"RMSD results shape: {R.results.rmsd.shape}")
    print(f"Time points: {R.results.rmsd[:, 1]}")
    print(f"RMSD values: {R.results.rmsd[:, 2]}")

    # Plot results
    import matplotlib.pyplot as plt
    plt.plot(R.results.rmsd[:, 1], R.results.rmsd[:, 2])
    plt.xlabel("Time (ps)")
    plt.ylabel("RMSD (Angstrom)")
    plt.savefig("rmsd_analysis.png")
```

--------------------------------

### Instantiate MDAnalysis Universe with Zarrtraj

Source: https://github.com/becksteinlab/zarrtraj/blob/main/examples/rmsd_yiip.ipynb

Creates an MDAnalysis `Universe` object by combining an in-memory topology file with a trajectory stored in a Google Cloud bucket in zarrtraj format. It specifies the topology format as PDB.

```python
import zarrtraj
import MDAnalysis as mda

u = mda.Universe(
    yiip_topology, "gcs://zarrtraj-test-data/yiip.zarrmd", topology_format="PDB"
)
```

--------------------------------

### Load .h5md file from disk using MDAnalysis

Source: https://github.com/becksteinlab/zarrtraj/blob/main/docs/source/api.md

Loads a simulation trajectory from a local .h5md file. Requires the topology file and the path to the .h5md file. This functionality is provided by the MDAnalysis Universe class, which zarrtraj integrates with.

```python
import zarrtraj
import MDAnalysis as mda
u = mda.Universe("topology.tpr", "trajectory.h5md")
```

--------------------------------

### Access Timestep Data and Observables with Python

Source: https://context7.com/becksteinlab/zarrtraj/llms.txt

Demonstrates how to access various properties of a trajectory timestep, including positions, velocities, forces, dimensions, and custom observable data stored in H5MD observables. It utilizes MDAnalysis for trajectory loading and zarrtraj for ZarrMD compatibility.

```python
import zarrtraj
import MDAnalysis as mda

u = mda.Universe("topology.tpr", "trajectory.zarrmd")

for ts in u.trajectory[:10]:  # First 10 frames
    # Basic timestep properties
    print(f"Frame: {ts.frame}")
    print(f"Time: {ts.time} ps")
    print(f"Step: {ts.data.get('step', 'N/A')}")

    # Coordinate data
    if ts.has_positions:
        print(f"Positions shape: {ts.positions.shape}")
        print(f"First atom position: {ts.positions[0]}")

    if ts.has_velocities:
        print(f"Velocities shape: {ts.velocities.shape}")

    if ts.has_forces:
        print(f"Forces shape: {ts.forces.shape}")

    # Box dimensions
    if ts.dimensions is not None:
        print(f"Box dimensions: {ts.dimensions}")
        print(f"Triclinic box:\n{ts.triclinic_dimensions}")

    # Observable data (custom data stored in H5MD observables group)
    for key, value in ts.data.items():
        if key not in ['step', 'time', 'dt']:
            print(f"Observable '{key}': {value}")
```

--------------------------------

### Run Cloud Trajectory Stride Benchmarks

Source: https://github.com/becksteinlab/zarrtraj/blob/main/joss_paper/figure_1.ipynb

This Python script executes the stride benchmark on trajectory data stored on AWS S3 (H5MD, ZarrMD). It uses the `time_stride` function to measure and print the iteration time for each cloud-based format.

```python
h5md_s3_stride_time = time_stride(h5md_s3_u.trajectory)
print(f"H5MD on S3 stride time: {h5md_s3_stride_time:.2f} seconds")
zarrmd_s3_stride_time = time_stride(zarrmd_s3_u.trajectory)
print(f"ZarrMD on S3 stride time: {zarrmd_s3_stride_time:.2f} seconds")
```

--------------------------------

### Load Cloud Trajectory Data for Benchmarking

Source: https://github.com/becksteinlab/zarrtraj/blob/main/joss_paper/figure_1.ipynb

This Python code loads trajectory data from AWS S3 in H5MD and ZarrMD formats. It configures AWS credentials and region, then prepares Universe objects for cloud-based stride benchmarking.

```python
import os
import MDAnalysis as mda
import zarrtraj

os.environ["S3_REGION_NAME"] = "us-west-1"
os.environ["AWS_PROFILE"] = "sample_profile"

TOPOL = "../zarrtraj/data/yiip_equilibrium/YiiP_system.pdb"
H5MD_S3_TRAJ = "s3://zarrtraj-test-data/yiip_aligned_uncompressed.h5md"
ZARRMD_TRAJ_S3 = "s3://zarrtraj-test-data/yiip_aligned_uncompressed.zarrmd"

h5md_s3_u = mda.Universe(TOPOL, H5MD_S3_TRAJ)
zarrmd_s3_u = mda.Universe(TOPOL, ZARRMD_TRAJ_S3)
```

--------------------------------

### Parse Atom Count from H5MD/ZarrMD with Python

Source: https://context7.com/becksteinlab/zarrtraj/llms.txt

Provides a static method `parse_n_atoms` from `ZARRH5MDReader` to efficiently determine the number of atoms in an H5MD or ZarrMD file without loading the entire trajectory. This is useful for validation or creating minimal topologies and supports local, remote, and multi-group files.

```python
import zarrtraj
from zarrtraj import ZARRH5MDReader

# Parse atom count from local file
n_atoms = ZARRH5MDReader.parse_n_atoms("trajectory.zarrmd")
print(f"Trajectory contains {n_atoms} atoms")

# Parse from remote file
n_atoms = ZARRH5MDReader.parse_n_atoms(
    "s3://my-bucket/trajectory.h5md",
    so={"anon": False}  # storage_options for authentication
)

# Specify particle group if multiple exist
n_atoms = ZARRH5MDReader.parse_n_atoms(
    "multi_group.h5md",
    group="protein"
)
```

--------------------------------

### Writing directly to Cloud Storage (.zarrmd format)

Source: https://github.com/becksteinlab/zarrtraj/blob/main/docs/source/api.md

Details on how to write trajectory data directly to cloud storage, currently only supported for the .zarrmd format.

```APIDOC
## Writing Directly to Cloud Storage

### Description
Write trajectory data directly to cloud storage services. This functionality is currently supported only for the `.zarrmd` format. For H5MD format, please raise an issue on the zarrtraj GitHub repository.

### Method
All datasets will be written using a chunking strategy of approximately 12MB per chunk. Exceptions apply if a single frame exceeds 12MB or if a dataset is smaller than 12MB.

#### AWS S3
```python
import zarrtraj
import MDAnalysis as mda
import os

os.environ["AWS_PROFILE"] = "sample_profile"
os.environ["AWS_REGION"] = "us-west-1"

u = mda.Universe(PSF, DCD) # Assuming PSF and DCD are defined
with mda.Writer("s3://sample-bucket/trajectory.zarrmd",
                n_atoms=u.atoms.n_atoms) as w:
    for ts in u.trajectory:
        w.write(u.atoms)
```

#### Google Cloud Storage
Change the URL protocol to `gcs` and authenticate using the gcloud CLI.

#### Azure Blob Storage or Data Lakes
Change the URL protocol to `abfs`/`adl`/`az` and authenticate using your storage account's connection string.

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import zarrtraj
import MDAnalysis as mda
from MDAnalysisTests.datafiles import PSF, DCD # Example data files
import os

os.environ["AWS_PROFILE"] = "sample_profile"
os.environ["AWS_REGION"] = "us-west-1"

u = mda.Universe(PSF, DCD)
with mda.Writer("s3://sample-bucket/trajectory.zarrmd",
                n_atoms=u.atoms.n_atoms) as w:
    for ts in u.trajectory:
        w.write(u.atoms)
```

### Response
#### Success Response (200)
Indicates successful writing of the trajectory data to the specified cloud storage location.

#### Response Example
```python
# No direct response example, but the operation completes without errors.
```
```

--------------------------------

### Read .h5md from Google Cloud Storage using MDAnalysis

Source: https://github.com/becksteinlab/zarrtraj/blob/main/docs/source/api.md

Reads a simulation trajectory from an .h5md file stored in Google Cloud Storage (GCS). Requires Application Default Credentials to be set up and the gcloud CLI to be authenticated with read access to the bucket. The GCS URL is passed to the MDAnalysis Universe constructor.

```python
import zarrtraj
import MDAnalysis as mda

u = mda.Universe("topology.tpr", "gcs://sample-bucket/trajectory.h5md")
```

--------------------------------

### Run Disk Trajectory Benchmarks (Dask and Serial)

Source: https://github.com/becksteinlab/zarrtraj/blob/main/joss_paper/figure_2.ipynb

Executes backbone RMSD calculations on trajectories stored on disk using both Dask (parallel) and serial backends. This snippet benchmarks XTC, ZarrMD, and H5MD formats, measuring the time taken for each.

```python
## Dask 

### XTC 

xtc_time_dask = time_backbone_RMSD(xtc_u, backend="dask", n_workers=4)

### ZarrMD, disk

zarrmd_disk_time_dask = time_backbone_RMSD(zarrmd_disk_u, backend="dask", n_workers=4)

## H5MD, disk

h5md_disk_time_dask = time_backbone_RMSD(h5md_disk_u, backend="dask", n_workers=4)

## Serial

## XTC

xtc_time_serial = time_backbone_RMSD(xtc_u, backend="serial")

## ZarrMD, disk

zarrmd_disk_time_serial = time_backbone_RMSD(zarrmd_disk_u, backend="serial")

## H5MD, disk

h5md_disk_time_serial = time_backbone_RMSD(h5md_disk_u, backend="serial")
```

--------------------------------

### Configure Sphinx Templates Path

Source: https://github.com/becksteinlab/zarrtraj/blob/main/docs/source/_templates/README.md

This snippet shows how to configure the path for custom templates in Sphinx. It involves setting the 'templates_path' variable in the 'conf.py' file. This allows Sphinx to find and use custom HTML files for overriding default page layouts.

```python
templates_path = ['_templates']
```

--------------------------------

### Trajectory Navigation API

Source: https://github.com/becksteinlab/zarrtraj/blob/main/docs/source/api.md

Methods for navigating through the trajectory frames.

```APIDOC
## GET /trajectory/n_frames

### Description
Retrieves the total number of frames in the trajectory.

### Method
GET

### Endpoint
/trajectory/n_frames

### Response
#### Success Response (200)
- **n_frames** (int) - The total number of frames in the trajectory.

#### Response Example
```json
{
  "n_frames": 1000
}
```
```

```APIDOC
## POST /trajectory/next

### Description
Advances the trajectory to the next frame. Returns the current timestep information.

### Method
POST

### Endpoint
/trajectory/next

### Response
#### Success Response (200)
- **Timestep** (object) - An object representing the current timestep of the trajectory.

#### Response Example
```json
{
  "frame": 1,
  "time": 10.0,
  "dt": 10.0,
  "coordinates": [...],
  "velocities": [...]
}
```
```

```APIDOC
## POST /trajectory/rewind

### Description
Resets the trajectory to the first frame.

### Method
POST

### Endpoint
/trajectory/rewind

### Response
#### Success Response (200)
- **Timestep** (object) - An object representing the first timestep of the trajectory.

#### Response Example
```json
{
  "frame": 0,
  "time": 0.0,
  "dt": 10.0,
  "coordinates": [...],
  "velocities": [...]
}
```
```

```APIDOC
## GET /trajectory/time

### Description
Retrieves the current time of the trajectory frame in MDAnalysis time units (typically picoseconds).

### Method
GET

### Endpoint
/trajectory/time

### Response
#### Success Response (200)
- **time** (float) - The current time of the trajectory frame.

#### Response Example
```json
{
  "time": 150.5
}
```
```

--------------------------------

### Upload H5MD Trajectory File to S3 Bucket using Boto3

Source: https://github.com/becksteinlab/zarrtraj/blob/main/docs/source/walkthrough.md

Uploads a locally written H5MD trajectory file to an AWS S3 bucket. This method requires the Boto3 package and assumes the H5MD file has already been created. It is recommended to configure chunking for optimal S3 performance.

```python
import MDAnalysisData
import MDAnalysis as mda
import os
import boto3

os.environ["AWS_PROFILE"] = "sample_profile"

```

--------------------------------

### ZARRMDWriter Class

Source: https://github.com/becksteinlab/zarrtraj/blob/main/docs/source/api.md

Initializes the ZARRMDWriter for creating H5MD format trajectories using Zarr. This class handles writing positions, velocities, and forces with options for unit conversion and compression.

```APIDOC
## ZARRMDWriter Class

### Description
Initializes the ZARRMDWriter for creating H5MD format trajectories using Zarr. This class handles writing positions, velocities, and forces with options for unit conversion and compression.

### Method
__init__

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **filename** (str) - Required - filename or URL to write to
* **n_atoms** (int) - Required - number of atoms in the system
* **n_frames** (int) - Optional - number of frames to be written in the output trajectory. If not provided, the trajectory will allocate more memory than necessary which may slow down trajectory write speed.
* **compressor** (numcodecs.Codec) - Optional - compressor to use for the Zarr datasets. Will be applied to all datasets
* **precision** (int) - Optional - applies the numcodecs.Quantize filter to Zarr datasets. Will be applied to all floating point datasets
* **storage_options** (dict) - Optional - options to pass to the storage backend via `fsspec`
* **convert_units** (bool) - Optional - Convert units from MDAnalysis to desired units [`True`]
* **positions** (bool) - Optional - Write positions into the trajectory [`True`]
* **velocities** (bool) - Optional - Write velocities into the trajectory [`True`]
* **forces** (bool) - Optional - Write forces into the trajectory [`True`]
* **timeunit** (str) - Optional - Option to convert values in the ‘time’ dataset to a custom unit, must be recognizable by MDAnalysis
* **lengthunit** (str) - Optional - Option to convert values in the ‘position/value’ dataset to a custom unit, must be recognizable by MDAnalysis
* **velocityunit** (str) - Optional - Option to convert values in the ‘velocity/value’ dataset to a custom unit, must be recognizable by MDAnalysis
* **forceunit** (str) - Optional - Option to convert values in the ‘force/value’ dataset to a custom unit, must be recognizable by MDAnalysis
* **author** (str) - Optional - Name of the author of the file
* **author_email** (str) - Optional - Email of the author of the file
* **creator** (str) - Optional - Software that wrote the file [`MDAnalysis`]
* **creator_version** (str) - Optional - Version of software that wrote the file [`MDAnalysis.__version__`]

### Request Example
```python
# Example instantiation (actual usage depends on context)
writer = ZARRMDWriter(
    filename='trajectory.zarr',
    n_atoms=100,
    n_frames=1000,
    compressor='default',
    precision=3,
    convert_units=True,
    positions=True,
    velocities=True,
    forces=True,
    timeunit='ps',
    lengthunit='nm',
    velocityunit='ns',
    forceunit='pN',
    author='John Doe',
    author_email='john.doe@example.com'
)
```

### Response
#### Success Response (200)
Initialization of the writer object.

#### Response Example
None (constructor does not return a value)

### Errors
* **RuntimeError** - when `Zarr` is not installed
* **ValueError** - when `n_atoms` is 0
* **ValueError** - when `n_frames` is provided and not positive
* **ValueError** - when `precision` is less than 0
* **ValueError** - when ‘positions`, ‘velocities’, and ‘forces’ are all set to `False`
* **ValueError** - when a unit is not recognized by MDAnalysis
* **TypeError** - when the input object is not a `Universe` or `AtomGroup`
* **ValueError** - when any of the optional timeunit, lengthunit, velocityunit, or forceunit keyword arguments are not recognized by MDAnalysis
* **ValueError** - when `convert_units` is set to `True` but the trajectory being written has no units
* **NoDataError** - when a timestep being written contains positions but no dimensions or vice versa
```

--------------------------------

### Configure Static File Path in Sphinx

Source: https://github.com/becksteinlab/zarrtraj/blob/main/docs/source/_static/README.md

This snippet shows how to configure the path for custom static files in a Sphinx project's `conf.py` file. The `html_static_path` variable takes a list of directories relative to the `conf.py` file. Files in these directories are copied to the output, potentially overwriting built-in files.

```python
html_static_path = ['_static']
```