Metadata-Version: 2.1
Name: unDumper
Version: 0.0.1
Summary: A fast and memory-efficient LAMMPS dump file reader with great developer experience
License: MIT
Author: Mohid Farooqi
Author-email: mu2farooqi@uwaterloo.ca
Requires-Python: >=3.12,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
Description-Content-Type: text/markdown

# LAMMPS Dump Reader
A fast and memory-efficient LAMMPS dump file reader with great developer experience.

## Project Charter
**Goal:** The goal of this project is to develop an open-source Python package that can read LAMMPS dump files into Python for further analysis.

**Objectives:**
1. The package will be unopinionated. All `dump` and `dump_modify` configurations will be easy to read, and all output data will be treated on equal footing.
2. The package will be easy to install using `pip`.
3. The package will have a good developer experience, including type-hinting and documentation.
4. The package will be fast and memory-efficient (only one frame will be loaded into memory at a time).

### Envisioned usage
There will be two overarching ways to use this package. The most forgiving way would be to use
```python
import dump_reader

# Bring whole dump file into memory
data = dump_reader.read_whole_dump("dump.lammpstrj")
```
This will bring the entire dump file into memory, so that it can be accessed at any point.

Because dump files may be large, you may not want to bring the whole file into memory at once. In this case, you can use
```python
import dump_reader

timesteps = []
positions = []

# Bring each snapshot in individually
for snapshot in dump_reader.read_dump("dump.lammpstrj"):
    timesteps.append(snapshot["TIMESTEP"])
    positions.append([])

    for atom in snapshot["ATOMS"]:
        if atom["element"] == "Li":
            positions[-1].append([atom["xu"], atom["yu"], atom["zu"]])
```
You would extract the information needed at the start of the script. `read_dump` would return an generator object, so that each snapshot is read in only as needed.

### Milestones
1. Implement `read_whole_dump`.
2. Implement `read_dump` using what was learned.
3. Potentially rewrite `read_whole_dump`, if performance improvements are expected.
4. Potentially rewrite the whole package with Rust bindings.


