Metadata-Version: 2.5
Name: reactra
Version: 0.1.0.dev1
Summary: Inspect, summarize, and plot exported molecular-simulation trajectories
Author: MechanismAtlas
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.12
Provides-Extra: plot
Requires-Dist: matplotlib<4,>=3.8; extra == 'plot'
Description-Content-Type: text/markdown

# Reactra

**Reaction Engine for Atomistic Catalytic Trajectory Reconstruction and Automation**

Reactra is the simulation platform being developed for the MechanismAtlas
enzyme-reaction ecosystem. This **0.1.0.dev1** public preview provides useful,
standalone tools for **exported simulation results**. The simulation engine is
currently private and is **not included in this distribution**.

The public tools work with ordinary PLUMED/COLVAR numeric tables, including
exported OPES traces. They require no model weights, accelerator, private
credentials, molecular structures, or mechanism definitions.

## Install

Python 3.12 or later:

```sh
python -m pip install reactra==0.1.0.dev1
# Optional plotting support:
python -m pip install 'reactra[plot]==0.1.0.dev1'
```

## Inspect a trajectory

Given a text file named `COLVAR` with PLUMED's standard header:

```text
#! FIELDS time cv opes.bias
0.0 0.20 0.0
0.1 0.23 -0.4
0.2 0.27 -0.8
```

```sh
reactra summary COLVAR
reactra summary COLVAR --columns cv opes.bias
reactra export-csv COLVAR --columns time cv --output selected.csv
reactra plot COLVAR --x time --y cv opes.bias --output traces.png
reactra fingerprint COLVAR
# Verify an independently recorded SHA-256 digest:
reactra fingerprint COLVAR --sha256 YOUR_64_CHARACTER_HEXADECIMAL_DIGEST
```

Summary reports the number of rows, per-column first/last/minimum/maximum/mean
and population standard deviation, and repeated or backward time steps. Summary
and CSV export stream the input instead of loading the trajectory into memory.
Identical repeated headers are accepted; changing headers, duplicate column names,
ragged rows, nonnumeric values, and NaN/infinity are refused with line diagnostics.

Plots use one panel per requested column and preserve row order. For a large file,
choose an explicit stride, for example `--stride 100`; plotting retains the
selected points in memory. Output supports PNG, SVG, and PDF. CSV and plot exports
refuse existing destinations and publish only after processing succeeds.

Units are preserved as recorded, not inferred. Statistics are linear, including
for angular columns: this release does not perform circular statistics or
periodic unwrapping. Time differences are not interpreted as completed continuous
sampling when a trace repeats or moves backward.

**A recorded bias or potential-energy trace is not a free-energy barrier.** These
tools do not infer reaction crossings, reconstruct free energies, estimate rates,
or qualify convergence. Artifact hashing checks byte identity against a supplied
digest; it does not establish scientific validity or authenticity.

## Python API

```python
from reactra.artifacts import fingerprint
from reactra.colvar import iter_colvar, summarize

report = summarize("COLVAR", columns=["cv"])
for row in iter_colvar("COLVAR"):
    print(row["time"], row["cv"])
identity = fingerprint("COLVAR")
```

CLI output is JSON. Exit codes are `0` for successful processing or a matching
digest, `1` for a digest mismatch, and `2` for invalid input or an I/O error.
The tools inspect explicitly named files and do not open or modify engine stores.

## Development status

This is an early, intentionally limited public component of a larger research
project. Its API may change before a stable release. It does not provide the
private engine's run, restart, YAML-authoring, or chemistry interfaces. Install
this public preview in its own environment if you also use a private Reactra
deployment; both distributions use the `reactra` package and command name.

The release source includes focused software tests. Run them with:

```sh
python -m pip install -e . pytest
python -m pytest
```
