### Install nim-mmcif from Source

Source: https://github.com/lucidrains/nim-mmcif/blob/main/README.md

Clone the repository and install nim-mmcif from source. This requires the Nim compiler to be installed separately.

```bash
git clone https://github.com/lucidrains/nim-mmcif
cd nim-mmcif
pip install -e .
```

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

### Install nim-mmcif from PyPI

Source: https://github.com/lucidrains/nim-mmcif/blob/main/README.md

Install the nim-mmcif package using pip. Ensure Python 3.8 or higher is installed.

```bash
pip install nim-mmcif
```

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

### Install nim-mmcif using Nimble

Source: https://github.com/lucidrains/nim-mmcif/blob/main/README.md

Install the nim-mmcif library using the Nimble package manager. This is the standard way to install Nim packages.

```shell
nimble install nim_mmcif
```

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

### Running Tests with Pytest

Source: https://github.com/lucidrains/nim-mmcif/blob/main/README.md

Install pytest and run tests for the project. This command executes all tests found in the 'tests/' directory with verbose output.

```bash
pip install pytest
pytest tests/ -v
```

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

### Automatic Build with Nim

Source: https://github.com/lucidrains/nim-mmcif/blob/main/README.md

Execute the automatic build script for the Nim project. Ensure Python is installed and accessible in your PATH.

```bash
python build_nim.py
```

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

### Get all atoms with properties (Python)

Source: https://github.com/lucidrains/nim-mmcif/blob/main/README.md

Retrieve a list of dictionaries, where each dictionary represents an atom and contains all its properties. Useful for detailed inspection of atom data.

```python
import nim_mmcif

# Get all atoms with their properties (returns list of dicts)
atoms = nim_mmcif.get_atoms("tests/test.mmcif")
for atom in atoms[:5]:  # Print first 5 atoms
    print(f"Atom {atom['id']}: {atom['label_atom_id']} at ({atom['x']}, {atom['y']}, {atom['z']})")
```

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

### Get All Atoms from mmCIF File

Source: https://context7.com/lucidrains/nim-mmcif/llms.txt

Retrieves all atoms from an mmCIF file as a list of dictionaries. Each dictionary contains detailed atom properties including coordinates, identifiers, and crystallographic data.

```python
from nim_mmcif import get_atoms

# Get all atoms with their properties
atoms = get_atoms("structure.mmcif")

# Iterate through atoms
for atom in atoms[:5]:
    print(f"Atom {atom['id']}: {atom['type_symbol']} ({atom['label_atom_id']})")
    print(f"  Position: ({atom['x']:.3f}, {atom['y']:.3f}, {atom['z']:.3f})")
    print(f"  Residue: {atom['label_comp_id']} {atom['label_seq_id']}")
    print(f"  Chain: {atom['label_asym_id']}")
# Output:
# Atom 1: N (N)
#   Position: (6.204, 16.869, 4.854)
#   Residue: VAL 1
#   Chain: A
```

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

### Get atom count directly (Python)

Source: https://github.com/lucidrains/nim-mmcif/blob/main/README.md

Retrieve the total number of atoms in an mmCIF file using the get_atom_count function. This is a direct and efficient way to get a single piece of information.

```python
import nim_mmcif

# Get atom count directly
count = nim_mmcif.get_atom_count("tests/test.mmcif")
print(f"File contains {count} atoms")
```

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

### Get only 3D coordinates (Python)

Source: https://github.com/lucidrains/nim-mmcif/blob/main/README.md

Extract only the 3D coordinates (x, y, z) of all atoms in an mmCIF file. This is useful when only positional information is needed.

```python
import nim_mmcif

# Get just the 3D coordinates
positions = nim_mmcif.get_atom_positions("tests/test.mmcif")
for i, (x, y, z) in enumerate(positions[:5]):
    print(f"Position {i}: ({x:.3f}, {y:.3f}, {z:.3f})")
```

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

### Get Atom Count from mmCIF File

Source: https://context7.com/lucidrains/nim-mmcif/llms.txt

Retrieves the number of atoms in an mmCIF file without loading all atom data. This is useful for quick file inspection or filtering large datasets before full parsing.

```python
from nim_mmcif import get_atom_count

# Get atom count from a single file
count = get_atom_count("structure.mmcif")
print(f"File contains {count} atoms")
# Output: File contains 7 atoms
```

```python
# Use for filtering large datasets
mmcif_files = ["small.mmcif", "medium.mmcif", "large.mmcif"]
large_structures = [f for f in mmcif_files if get_atom_count(f) > 1000]
print(f"Found {len(large_structures)} structures with >1000 atoms")
```

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

### Manual Build with Nimble

Source: https://github.com/lucidrains/nim-mmcif/blob/main/README.md

Build the project using nimble tasks. Use 'nimble build' for a debug version and 'nimble buildRelease' for an optimized release version.

```bash
# Build using nimble tasks
nimble build         # Build debug version
nimble buildRelease  # Build optimized release version
```

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

### Batch parse and access coordinates in Nim

Source: https://context7.com/lucidrains/nim-mmcif/llms.txt

Demonstrates how to parse multiple mmCIF files and iterate through atom coordinates using Nim.

```nim
let filepaths = @["structure1.mmcif", "structure2.mmcif"]
let results = mmcif_parse_batch(filepaths)
for parsed in results:
  echo "Structure has ", parsed.atoms.len, " atoms"

# Use coordinate aliases
for atom in data.atoms:
  echo "Position: (", atom.x, ", ", atom.y, ", ", atom.z, ")"
```

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

### Handle errors and validate files in Python

Source: https://context7.com/lucidrains/nim-mmcif/llms.txt

Provides patterns for catching file and parsing exceptions, as well as validating file existence and size before processing.

```python
from nim_mmcif import parse_mmcif, get_atom_count
from pathlib import Path

# Handle missing files
try:
    data = parse_mmcif("nonexistent.mmcif")
except FileNotFoundError as e:
    print(f"File not found: {e}")

# Handle invalid inputs
try:
    data = parse_mmcif("")
except (FileNotFoundError, ValueError) as e:
    print(f"Invalid input: {e}")

# Handle parsing errors
try:
    data = parse_mmcif("corrupted.mmcif")
except RuntimeError as e:
    print(f"Parse error: {e}")

# Safe batch processing with validation
def safe_parse_batch(file_patterns):
    """Parse files with error handling for each file."""
    results = {}
    for pattern in file_patterns:
        try:
            data = parse_mmcif(pattern)
            if isinstance(data, dict) and 'atoms' in data:
                results[pattern] = data
            else:
                results.update(data)
        except (FileNotFoundError, RuntimeError) as e:
            print(f"Skipping {pattern}: {e}")
    return results

# Validate files before processing
mmcif_files = list(Path(".").glob("*.mmcif"))
valid_files = [f for f in mmcif_files if f.exists() and f.stat().st_size > 0]
```

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

### Filter and Group Atoms

Source: https://context7.com/lucidrains/nim-mmcif/llms.txt

Demonstrates basic filtering of backbone atoms and grouping atoms by their chain identifier.

```python
# Filter backbone atoms
backbone_atoms = [a for a in atoms if a['label_atom_id'] in ['N', 'CA', 'C', 'O']]
print(f"Found {len(backbone_atoms)} backbone atoms")

# Group atoms by chain
from collections import defaultdict
chains = defaultdict(list)
for atom in atoms:
    chains[atom['label_asym_id']].append(atom)
for chain_id, chain_atoms in chains.items():
    print(f"Chain {chain_id}: {len(chain_atoms)} atoms")
```

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

### Access Atom Properties

Source: https://context7.com/lucidrains/nim-mmcif/llms.txt

Demonstrates accessing individual atom properties and coordinates using the Atom dataclass.

```python
from nim_mmcif import parse_mmcif, Atom

data = parse_mmcif("structure.mmcif", as_dataclass=True)
atom: Atom = data.atoms[0]

# Access all atom properties with dot notation
print(f"Type: {atom.type}")           # "ATOM" or "HETATM"
print(f"ID: {atom.id}")               # Atom serial number
print(f"Element: {atom.type_symbol}") # Element symbol (N, C, O, etc.)
print(f"Atom name: {atom.label_atom_id}")  # Atom name (CA, CB, N, etc.)
print(f"Residue: {atom.label_comp_id}")    # Residue name (VAL, ALA, etc.)
print(f"Chain: {atom.label_asym_id}")      # Chain identifier
print(f"Sequence: {atom.label_seq_id}")    # Residue sequence number
# Output:
# Type: ATOM
# ID: 1
# Element: N
# Atom name: N
# Residue: VAL
# Chain: A
# Sequence: 1

# Coordinate access (both forms available)
print(f"Cartn_x: {atom.Cartn_x}, x: {atom.x}")  # x-coordinate
print(f"Cartn_y: {atom.Cartn_y}, y: {atom.y}")  # y-coordinate
print(f"Cartn_z: {atom.Cartn_z}, z: {atom.z}")  # z-coordinate

# Get position as tuple
pos = atom.position  # Returns (x, y, z) tuple
print(f"Position tuple: {pos}")

# Crystallographic properties
print(f"Occupancy: {atom.occupancy}")
print(f"B-factor: {atom.B_iso_or_equiv}")

# Convert single atom to dictionary
atom_dict = atom.to_dict()
```

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

### Parse mmCIF file and iterate atoms (Nim)

Source: https://github.com/lucidrains/nim-mmcif/blob/main/README.md

Parse an mmCIF file in Nim and iterate through its atoms to access properties. This demonstrates basic Nim usage for the library.

```nim
import nim_mmcif

# Parse an mmCIF file
let data = mmcif_parse("tests/test.mmcif")
echo "Found ", data.atoms.len, " atoms"

# Iterate through atoms
for atom in data.atoms[0..<min(5, data.atoms.len)]:
  echo "Atom ", atom.id, ": ", atom.label_atom_id, 
       " at ( ", atom.Cartn_x, ", ", atom.Cartn_y, ", ", atom.Cartn_z, ")"

# Access specific atom properties
if data.atoms.len > 0:
  let firstAtom = data.atoms[0]
  echo "Chain: ", firstAtom.label_asym_id
  echo "Residue: ", firstAtom.label_comp_id
  echo "B-factor: ", firstAtom.B_iso_or_equiv
```

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

### Batch Parse mmCIF Files with Nim mmCIF

Source: https://context7.com/lucidrains/nim-mmcif/llms.txt

Parses multiple mmCIF files efficiently in a single operation. Accepts a list of file paths, a single path, or glob patterns. Returns a list of results for file lists, or a dictionary mapping paths to results for glob patterns.

```python
from nim_mmcif import parse_mmcif_batch

# Parse a list of specific files (returns list of results)
files = [
    "structure1.mmcif",
    "structure2.mmcif",
    "structure3.mmcif"
]
results = parse_mmcif_batch(files)

for i, data in enumerate(results):
    atoms = data['atoms']
    chains = set(atom['label_asym_id'] for atom in atoms)
    residues = set((atom['label_asym_id'], atom['label_seq_id']) for atom in atoms)
    print(f"Structure {i+1}: {len(atoms)} atoms, {len(chains)} chains, {len(residues)} residues")
# Output:
# Structure 1: 3 atoms, 1 chains, 1 residues
# Structure 2: 3 atoms, 2 chains, 2 residues
# Structure 3: 7 atoms, 1 chains, 1 residues
```

```python
# Batch processing with glob pattern (returns dict mapping paths to results)
results = parse_mmcif_batch("pdb_files/*.mmcif")
for filepath, data in results.items():
    print(f"{filepath}: {len(data['atoms'])} atoms")
```

```python
# Mix glob patterns and regular paths
results = parse_mmcif_batch([
    "specific_file.mmcif",
    "structures/*.mmcif",
    "models/model_?.mmcif"
])
```

```python
# Batch processing with dataclass output
results = parse_mmcif_batch(files, as_dataclass=True)
for result in results:
    print(f"Structure has {result.atom_count} atoms in {len(result.chains)} chain(s)")
```

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

### Batch process multiple mmCIF files (Python)

Source: https://github.com/lucidrains/nim-mmcif/blob/main/README.md

Efficiently parse multiple mmCIF files in a single operation using parse_mmcif_batch. This is useful for processing large datasets.

```python
import nim_mmcif

# List of mmCIF files to process
files = [
    "path/to/structure1.mmcif",
    "path/to/structure2.mmcif",
    "path/to/structure3.mmcif"
]

# Parse all files in batch (returns list when no globs used)
results = nim_mmcif.parse_mmcif_batch(files)
```

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

### Structural Analysis Utilities

Source: https://github.com/lucidrains/nim-mmcif/blob/main/README.md

Utility functions to extract specific structural information from an mmCIF file.

```APIDOC
## Structural Analysis Utilities

### Functions
- **get_atom_count(filepath: str) -> int**
  - Returns the number of atoms in an mmCIF file.
- **get_atoms(filepath: str) -> list[dict]**
  - Returns all atoms from an mmCIF file as a list of dictionaries.
- **get_atom_positions(filepath: str) -> list[tuple[float, float, float]]**
  - Returns 3D coordinates of all atoms as a list of (x, y, z) tuples.
```

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

### Parse mmCIF file and access data as dictionary (Python)

Source: https://github.com/lucidrains/nim-mmcif/blob/main/README.md

Parse an mmCIF file and access its data using dictionary notation. This is the default behavior of parse_mmcif.

```python
from nim_mmcif import parse_mmcif

# Parse an mmCIF file (returns dict by default)
data = parse_mmcif("tests/test.mmcif")
print(f"Found {len(data['atoms'])} atoms")

# Access atom properties using dictionary notation
first_atom = data['atoms'][0]
print(f"Atom {first_atom['id']}: {first_atom['label_atom_id']}")
print(f"Position: ({first_atom['x']}, {first_atom['y']}, {first_atom['z']})")
```

```python
# Parse multiple files using glob patterns
results = parse_mmcif("tests/*.mmcif")
for filepath, data in results.items():
    print(f"{filepath}: {len(data['atoms'])} atoms")
```

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

### Parse mmCIF file with dataclass access (Python)

Source: https://github.com/lucidrains/nim-mmcif/blob/main/README.md

Parse an mmCIF file with dataclass support for cleaner dot notation access. This provides convenient properties and methods for accessing data.

```python
from nim_mmcif import parse_mmcif, parse_mmcif_batch

# Parse with dataclass support for cleaner dot notation access
data = parse_mmcif("tests/test.mmcif", as_dataclass=True)
print(f"Found {data.atom_count} atoms")

# Access atom properties using dot notation
first_atom = data.atoms[0]
print(f"Atom {first_atom.id}: {first_atom.label_atom_id}")
print(f"Position: ({first_atom.x}, {first_atom.y}, {first_atom.z})")
print(f"Chain: {first_atom.label_asym_id}, Residue: {first_atom.label_comp_id}")

# Use convenience properties and methods
print(f"Unique chains: {data.chains}")
print(f"Number of residues: {len(data.residues)}")

# Get all atoms from a specific chain
chain_a_atoms = data.get_chain('A')

# Get all atoms from a specific residue
residue_atoms = data.get_residue('A', 1)

# Get all positions as tuples
positions = data.positions  # List of (x, y, z) tuples
```

```python
# Batch processing with dataclasses
results = parse_mmcif_batch(["tests/test1.mmcif", "tests/test2.mmcif"], as_dataclass=True)
for result in results:
    print(f"Structure has {result.atom_count} atoms in {len(result.chains)} chain(s)")
```

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

### Nim API Usage

Source: https://context7.com/lucidrains/nim-mmcif/llms.txt

Direct usage of the library in Nim for high-performance structural data processing.

```nim
import nim_mmcif

# Parse an mmCIF file
let data = mmcif_parse("structure.mmcif")
echo "Found ", data.atoms.len, " atoms"

# Iterate through atoms
for atom in data.atoms[0..<min(5, data.atoms.len)]:
  echo "Atom ", atom.id, ": ", atom.label_atom_id,
       " at (", atom.Cartn_x, ", ", atom.Cartn_y, ", ", atom.Cartn_z, ")"

# Access specific atom properties
if data.atoms.len > 0:
  let firstAtom = data.atoms[0]
  echo "Type: ", firstAtom.`type`       # ATOM or HETATM
  echo "Element: ", firstAtom.type_symbol
  echo "Chain: ", firstAtom.label_asym_id
  echo "Residue: ", firstAtom.label_comp_id
  echo "B-factor: ", firstAtom.B_iso_or_equiv
```

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

### Parse mmCIF Files with Nim mmCIF

Source: https://context7.com/lucidrains/nim-mmcif/llms.txt

Parses a single mmCIF file or multiple files using glob patterns. Supports dictionary-based access by default, or dataclass-based access when `as_dataclass=True` is specified.

```python
from nim_mmcif import parse_mmcif

# Parse a single mmCIF file (returns dictionary by default)
data = parse_mmcif("structure.mmcif")
print(f"Found {len(data['atoms'])} atoms")

# Access atom properties using dictionary notation
first_atom = data['atoms'][0]
print(f"Atom {first_atom['id']}: {first_atom['label_atom_id']}")
print(f"Position: ({first_atom['x']}, {first_atom['y']}, {first_atom['z']})")
print(f"Chain: {first_atom['label_asym_id']}, Residue: {first_atom['label_comp_id']}")
print(f"B-factor: {first_atom['B_iso_or_equiv']}, Occupancy: {first_atom['occupancy']}")
# Output:
# Found 7 atoms
# Atom 1: N
# Position: (6.204, 16.869, 4.854)
# Chain: A, Residue: VAL
# B-factor: 49.05, Occupancy: 1.0
```

```python
# Parse with dataclass support for cleaner dot notation access
data = parse_mmcif("structure.mmcif", as_dataclass=True)
first_atom = data.atoms[0]
print(f"Atom {first_atom.id}: {first_atom.label_atom_id} at {first_atom.position}")
```

```python
# Parse multiple files using glob patterns (returns dict mapping paths to results)
results = parse_mmcif("structures/*.mmcif")
for filepath, data in results.items():
    print(f"{filepath}: {len(data['atoms'])} atoms")
```

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

### Nim Usage

Source: https://context7.com/lucidrains/nim-mmcif/llms.txt

Direct usage in Nim applications for maximum performance. The Nim API provides the same functionality with native types.

```APIDOC
## Nim Usage

### Description
Direct usage in Nim applications for maximum performance. The Nim API provides the same functionality with native types.

### Method
GET

### Endpoint
/nim/parse_mmcif

### Parameters
#### Query Parameters
- **filepath** (string) - Required - Path to the mmCIF file.

### Request Example
```nim
import nim_mmcif

let data = mmcif_parse("structure.mmcif")
```

### Response
#### Success Response (200)
- **data** (object) - An object containing parsed mmCIF data with native Nim types.
  - **atoms** (seq of Atom) - Sequence of atom objects.

#### Response Example
```nim
# Example of accessing atom properties
if data.atoms.len > 0:
  let firstAtom = data.atoms[0]
  echo "Atom ID: ", firstAtom.id
  echo "Atom Name: ", firstAtom.label_atom_id
  echo "Coordinates: (", firstAtom.Cartn_x, ", ", firstAtom.Cartn_y, ", ", firstAtom.Cartn_z, ")"
```
```

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

### Batch Parse mmCIF Files with Glob Pattern

Source: https://github.com/lucidrains/nim-mmcif/blob/main/README.md

Parses multiple mmCIF files matching a glob pattern using `parse_mmcif_batch`. Returns a dictionary mapping file paths to parsed data. Ensure the glob pattern correctly targets the desired files.

```python
# Batch processing with glob patterns (returns dict)
results = nim_mmcif.parse_mmcif_batch("path/to/*.mmcif")
for filepath, data in results.items():
    print(f"{filepath}: {len(data['atoms'])} atoms")
```

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

### get_atoms

Source: https://context7.com/lucidrains/nim-mmcif/llms.txt

Retrieves all atoms from an mmCIF file as a list of dictionaries containing atom properties.

```APIDOC
## get_atoms

### Description
Get all atoms from an mmCIF file as a list of dictionaries. Each dictionary contains atom properties including coordinates, identifiers, and crystallographic data.

### Parameters
#### Arguments
- **path** (string) - Required - Path to the mmCIF file.

### Response
- **atoms** (list of dict) - A list where each element represents an atom with its associated properties.
```

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

### Extract Atom Positions

Source: https://context7.com/lucidrains/nim-mmcif/llms.txt

Extracts 3D coordinates and performs basic structural calculations like center of mass and pairwise distances.

```python
from nim_mmcif import get_atom_positions
import math

# Get all atom coordinates
positions = get_atom_positions("structure.mmcif")

# Print first few positions
for i, (x, y, z) in enumerate(positions[:5]):
    print(f"Position {i}: ({x:.3f}, {y:.3f}, {z:.3f})")
# Output:
# Position 0: (6.204, 16.869, 4.854)
# Position 1: (6.913, 18.117, 5.114)
# Position 2: (6.034, 19.305, 4.768)
# Position 3: (4.809, 19.223, 4.925)

# Calculate center of mass
n = len(positions)
cx = sum(p[0] for p in positions) / n
cy = sum(p[1] for p in positions) / n
cz = sum(p[2] for p in positions) / n
print(f"Center of mass: ({cx:.3f}, {cy:.3f}, {cz:.3f})")

# Calculate pairwise distances
def distance(p1, p2):
    return math.sqrt(sum((a - b) ** 2 for a, b in zip(p1, p2)))

if len(positions) >= 2:
    d = distance(positions[0], positions[1])
    print(f"Distance between first two atoms: {d:.3f} Angstroms")
```

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

### Batch Parse mmCIF Files with Mixed Paths

Source: https://github.com/lucidrains/nim-mmcif/blob/main/README.md

Parses mmCIF files using a list containing a mix of specific file paths and glob patterns. The function returns a dictionary mapping file paths to their parsed data. This method is efficient for processing varied collections of structures.

```python
# Mix of glob patterns and regular paths (returns dict)
results = nim_mmcif.parse_mmcif_batch([
    "specific_file.mmcif",
    "structures/*.mmcif",
    "models/model_?.mmcif"
])
for filepath, data in results.items():
    print(f"{filepath}: {len(data['atoms'])} atoms")
```

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

### parse_mmcif_batch

Source: https://context7.com/lucidrains/nim-mmcif/llms.txt

Parses multiple mmCIF files in a single batch operation for improved performance.

```APIDOC
## parse_mmcif_batch

### Description
Parses multiple mmCIF files in a single batch operation. Accepts a list of file paths, a single path, or glob patterns.

### Parameters
#### Arguments
- **paths** (list or string) - Required - A list of file paths, a single path, or a glob pattern.
- **as_dataclass** (boolean) - Optional - If True, returns results as dataclasses.
```

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

### Process and Analyze mmCIF Results

Source: https://github.com/lucidrains/nim-mmcif/blob/main/README.md

Iterates through parsed mmCIF results, printing structure information, unique chain IDs, and residue counts. Requires prior parsing of mmCIF data.

```python
for i, data in enumerate(results):
    print(f"Structure {i+1}: {len(data['atoms'])} atoms")
    
    # Analyze each structure
    atoms = data['atoms']
    if atoms:
        # Get unique chain IDs
        chains = set(atom['label_asym_id'] for atom in atoms)
        print(f"  Chains: {', '.join(sorted(chains))}")
        
        # Count residues
        residues = set((atom['label_asym_id'], atom['label_seq_id']) 
                      for atom in atoms)
        print(f"  Residues: {len(residues)}")
```

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

### get_atom_positions

Source: https://context7.com/lucidrains/nim-mmcif/llms.txt

Extracts 3D coordinates of all atoms as a list of (x, y, z) tuples. Optimized for computational analysis, machine learning pipelines, and structural calculations.

```APIDOC
## get_atom_positions

### Description
Extract 3D coordinates of all atoms as a list of (x, y, z) tuples. Optimized for computational analysis, machine learning pipelines, and structural calculations.

### Method
GET

### Endpoint
/api/get_atom_positions

### Parameters
#### Query Parameters
- **filepath** (string) - Required - Path to the mmCIF file.

### Request Example
```python
from nim_mmcif import get_atom_positions

positions = get_atom_positions("structure.mmcif")
```

### Response
#### Success Response (200)
- **positions** (list of tuples) - A list where each tuple contains the (x, y, z) coordinates of an atom.

#### Response Example
```json
{
  "positions": [
    [6.204, 16.869, 4.854],
    [6.913, 18.117, 5.114],
    [6.034, 19.305, 4.768],
    [4.809, 19.223, 4.925]
  ]
}
```
```

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

### parse_mmcif

Source: https://github.com/lucidrains/nim-mmcif/blob/main/README.md

Parses a single mmCIF file or files matching a glob pattern.

```APIDOC
## parse_mmcif

### Description
Parses an mmCIF file or files matching a glob pattern.

### Parameters
#### Arguments
- **filepath** (str) - Required - Path to mmCIF file or glob pattern.
- **as_dataclass** (bool) - Optional - If True, returns MmcifData dataclass(es) with dot notation access.

### Response
- **Returns** (dict | MmcifData | dict[str, dict] | dict[str, MmcifData]) - Returns a dictionary or MmcifData instance for single files, or a mapping of file paths to data for glob patterns.
```

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

### Atom Dataclass

Source: https://context7.com/lucidrains/nim-mmcif/llms.txt

Represents a single atom with typed properties accessible via dot notation. Includes coordinate aliases and position property for convenient access.

```APIDOC
## Atom Dataclass

### Description
Represents a single atom with typed properties accessible via dot notation. Includes coordinate aliases and position property for convenient access.

### Method
GET

### Endpoint
/api/atoms/{atom_id}

### Parameters
#### Path Parameters
- **atom_id** (integer) - Required - The unique identifier of the atom.

#### Query Parameters
- **filepath** (string) - Required - Path to the mmCIF file.
- **as_dataclass** (boolean) - Optional - If true, returns atom data as Atom dataclass. Defaults to false.

### Request Example
```python
from nim_mmcif import parse_mmcif

data = parse_mmcif("structure.mmcif", as_dataclass=True)
atom = data.atoms[0]
```

### Response
#### Success Response (200)
- **Atom** (object) - An object representing a single atom.
  - **type** (string) - "ATOM" or "HETATM".
  - **id** (integer) - Atom serial number.
  - **type_symbol** (string) - Element symbol (e.g., 'N', 'CA', 'C', 'O').
  - **label_atom_id** (string) - Atom name (e.g., 'CA', 'CB', 'N').
  - **label_comp_id** (string) - Residue name (e.g., 'VAL', 'ALA').
  - **label_asym_id** (string) - Chain identifier.
  - **label_seq_id** (integer) - Residue sequence number.
  - **Cartn_x**, **Cartn_y**, **Cartn_z** (float) - Cartesian coordinates.
  - **x**, **y**, **z** (float) - Aliases for Cartesian coordinates.
  - **position** (tuple) - (x, y, z) coordinate tuple.
  - **occupancy** (float) - Occupancy value.
  - **B_iso_or_equiv** (float) - B-factor.

#### Response Example
```json
{
  "type": "ATOM",
  "id": 1,
  "type_symbol": "N",
  "label_atom_id": "N",
  "label_comp_id": "VAL",
  "label_asym_id": "A",
  "label_seq_id": 1,
  "Cartn_x": 6.204,
  "Cartn_y": 16.869,
  "Cartn_z": 4.854,
  "x": 6.204,
  "y": 16.869,
  "z": 4.854,
  "position": [6.204, 16.869, 4.854],
  "occupancy": 1.0,
  "B_iso_or_equiv": 20.0
}
```
```

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

### get_atom_count

Source: https://context7.com/lucidrains/nim-mmcif/llms.txt

Retrieves the number of atoms in an mmCIF file without loading the full atom data.

```APIDOC
## get_atom_count

### Description
Get the number of atoms in an mmCIF file without loading all atom data. Useful for quick file inspection.

### Parameters
#### Arguments
- **path** (string) - Required - Path to the mmCIF file.

### Response
- **count** (integer) - The total number of atoms in the file.
```

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

### parse_mmcif

Source: https://context7.com/lucidrains/nim-mmcif/llms.txt

Parses an mmCIF file or files matching a glob pattern, returning structure data including atom records, coordinates, and metadata.

```APIDOC
## parse_mmcif

### Description
Parses an mmCIF file or files matching a glob pattern. Returns parsed structure data with atom records, coordinates, and metadata. Supports both dictionary and dataclass return formats.

### Parameters
#### Arguments
- **path** (string) - Required - Path to the mmCIF file or a glob pattern.
- **as_dataclass** (boolean) - Optional - If True, returns data as a dataclass for dot notation access instead of a dictionary.

### Response
- **data** (dict or dataclass) - Contains atom records, coordinates, and metadata.
```

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

### Use MmcifData Dataclass

Source: https://context7.com/lucidrains/nim-mmcif/llms.txt

Utilizes the MmcifData container for typed access to parsed mmCIF data, including chain and residue filtering.

```python
from nim_mmcif import parse_mmcif, MmcifData, Atom

# Parse with dataclass support
data: MmcifData = parse_mmcif("structure.mmcif", as_dataclass=True)

# Access convenience properties
print(f"Total atoms: {data.atom_count}")
print(f"Unique chains: {data.chains}")
print(f"Unique residues: {len(data.residues)}")
# Output:
# Total atoms: 7
# Unique chains: {'A'}
# Unique residues: 1

# Get all positions as tuples
positions = data.positions  # List of (x, y, z) tuples

# Get atoms from a specific chain
chain_a_atoms = data.get_chain('A')
print(f"Chain A has {len(chain_a_atoms)} atoms")

# Get atoms from a specific residue
residue_atoms = data.get_residue('A', 1)
print(f"Residue A:1 has {len(residue_atoms)} atoms")

# Convert back to dictionary format
dict_data = data.to_dict()
print(f"Converted back: {len(dict_data['atoms'])} atoms")
```

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

### MmcifData Dataclass

Source: https://context7.com/lucidrains/nim-mmcif/llms.txt

Container dataclass for parsed mmCIF data with typed atom access, convenience properties, and methods for chain and residue filtering. Provides clean dot notation access to all atom properties.

```APIDOC
## MmcifData Dataclass

### Description
Container dataclass for parsed mmCIF data with typed atom access, convenience properties, and methods for chain and residue filtering. Provides clean dot notation access to all atom properties.

### Method
POST

### Endpoint
/api/parse_mmcif

### Parameters
#### Request Body
- **filepath** (string) - Required - Path to the mmCIF file.
- **as_dataclass** (boolean) - Optional - If true, returns data as MmcifData dataclass. Defaults to false.

### Request Example
```python
from nim_mmcif import parse_mmcif

data = parse_mmcif("structure.mmcif", as_dataclass=True)
```

### Response
#### Success Response (200)
- **MmcifData** (object) - An object representing the parsed mmCIF data.
  - **atom_count** (integer) - Total number of atoms.
  - **chains** (set) - Set of unique chain identifiers.
  - **residues** (list) - List of unique residues.
  - **positions** (list of tuples) - List of (x, y, z) coordinates for all atoms.
  - **atoms** (list of Atom objects) - List of Atom objects.

#### Response Example
```json
{
  "atom_count": 7,
  "chains": ["A"],
  "residues": [{"chain_id": "A", "residue_id": 1, "residue_name": "VAL"}],
  "positions": [[6.204, 16.869, 4.854]],
  "atoms": [
    {
      "type": "ATOM",
      "id": 1,
      "type_symbol": "N",
      "label_atom_id": "N",
      "label_comp_id": "VAL",
      "label_asym_id": "A",
      "label_seq_id": 1,
      "Cartn_x": 6.204,
      "Cartn_y": 16.869,
      "Cartn_z": 4.854,
      "occupancy": 1.0,
      "B_iso_or_equiv": 20.0
    }
  ]
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.