Metadata-Version: 2.4
Name: lammps_ast
Version: 0.1.9
Summary: A LAMMPS script parser and sanitizer using Lark
Home-page: https://github.com/ethanholbrook/LAMMPS-AST
Author: Juan C. Verduzco, Ethan W. Holbrook
Author-email: holbrooe@purdue.edu
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: lark-parser>=0.12.0
Requires-Dist: colorama
Requires-Dist: graphviz
Requires-Dist: zss
Requires-Dist: pydot
Requires-Dist: simpleeval
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# LAMMPS-AST

`LAMMPS-AST` is a Python package for sanitizing and parsing LAMMPS input scripts into abstract syntax trees (ASTs). It is built on [Lark](https://github.com/lark-parser/lark) and is intended for structural analysis, validation, comparison, and downstream workflows around LAMMPS input files.

## What It Provides

- script sanitization before parsing
- parsing of LAMMPS input scripts into ASTs
- AST transformation and comparison utilities
- repository examples showing how the parser can be used in notebook and pipeline workflows

## Install

Install from PyPI:

```bash
pip install lammps_ast
```

If you need the optional visualization tooling used in some example workflows, you may also want a local Graphviz install.

## Minimal Usage

```python
from lammps_ast.sanitizer import sanitize
from lammps_ast.parser import parse_to_AST

script = """
units metal
atom_style atomic
boundary p p p
"""

sanitized = sanitize(script)
tree, errors = parse_to_AST(sanitized, lint=True)
```

`parse_to_AST(..., lint=True)` returns a parse tree plus collected parse errors. With `lint=False`, it behaves like a direct parser call and returns either a tree or an exception object.

## Repository Layout

- `lammps_ast/`: package source, including parser, sanitizer, grammar, and AST utilities
- `examples/`: small examples of using the parser directly
- `publication/`: notebook-based workflow used for the publication-oriented evaluation example
- `ez-pipeline/`: script-oriented evaluation pipeline built on top of `lammps_ast`

The PyPI distribution is focused on the `lammps_ast` package itself. The notebook and pipeline folders are repository examples and supporting workflows.

## Development Install

To work from a local clone:

```bash
pip install -e .
```

## Citation

If you use `LAMMPS-AST` or the evaluation workflow in academic work, please cite the associated publication.

```bibtex
@article{lammps_ast_paper,
  title        = {Evaluating LLM-generated code for domain-specific languages: molecular dynamics with LAMMPS},
  author       = {Holbrook, Ethan W. and Verduzco, Juan C. and Strachan, Alejandro},
  year         = {2026},
  eprint       = {2603.20630},
  archivePrefix = {arXiv},
  primaryClass = {cs.SE},
  url          = {https://arxiv.org/abs/2603.20630}
}
```
