# _eightyseven_—read and write `gro` files, pretty quickly

A `gro` file (Gromos87) describes molecular structures in a plain-text format.
(See [the Gromacs manual][gro_man] or [the old pretty manual][gro_man_legacy].)

Note that, for now, only reading and writing of the classic fixed format is
supported. The additional precision reading mode is on the agenda.

_eightyseven_ can format the atoms section of a gro file in a parallel fashion,
with `WriteGro::write_par` and related methods.

This library comes with its own `Structure` type, which mirrors the information
that is stored in `gro` files. For `Structure`, the `ReadGro`, `WriteGro`, and
`WriteGroPar` traits are implemented. The reading and writing functionality
provided by these traits are provided as good default implementations, which
rely on a couple of easy to implement bridging functions. This makes
implementing the traits for custom types very easy.

Moreover, rather specialized readers that read only a subset of the atom line
fields can be implemented easily and efficiently by setting the flags of the
`ReadGro::PARSE_LIST` constant.

```rust
use eightyseven::structure::Structure;

// Read the structure from a file.
use eightyseven::reader::ReadGro;
let mut structure = Structure::open_gro("tests/eq.gro")?;
println!(" title: {}", structure.title);
println!("natoms: {}", structure.natoms());

// Modify the structure.
// For example, center the structure such that the `BB` beads are centered.
let bb_positions = structure
    .atoms
    .iter()
    .filter(|&atom| atom.atomname.as_str() == "BB")
    .map(|atom| atom.position);
let bb_center = bb_positions.clone().sum::<glam::Vec3>() / bb_positions.count() as f32;

for atom in &mut structure.atoms {
    atom.position -= bb_center;
}

// And write the structure.
use eightyseven::writer::WriteGro;
structure.save_gro("eq_offset.gro")?;

// Or, for fast writing of large files, format the atom section in parallel.
use eightyseven::writer::WriteGroPar;
structure.save_gro_par("eq_offset.gro")?;

// For both single-threaded and parallel formatting, generic writers exist as well.
// They can write to any type that implements `io::Write`.
structure.write_par(&mut std::io::empty())?;
```

## Documentation

Documentation is available at [docs.rs][docs]. Or locally, with `cargo doc`.

## Installation

The usual installation procedure applies.

```console
$ cargo add eightyseven
```

## Tests and benchmarks

Tests and benchmarks are included. Run them in the cloned repository.

```console
$ git clone https://git.sr.ht/~ma3ke/eightyseven
$ cd eightyseven
$ cargo test
$ cargo bench
```

## See also

I have written an `xtc` reader library as well, called [_molly_][molly].
`xtc` is a compressed trajectory format for Gromacs.

The graphing data format that is output by Gromacs analysis commands is `xvg`.
[_phrace_][phrace] is a terminal viewer for that data format.

[gro_man]: https://manual.gromacs.org/current/reference-manual/file-formats.html#gro
[gro_man_legacy]: https://manual.gromacs.org/archive/5.0.3/online/gro.html
[docs]: https://docs.rs/eightyseven/latest
[molly]: https://git.sr.ht/~ma3ke/molly
[phrace]: https://git.sr.ht/~ma3ke/phrace

---

By Marieke Westendorp, 2024.