reactra 0.1.0.dev1__py3-none-any.whl

reactra/__init__.py

@@ -0,0 +1,3 @@
+"""Public Reactra tools for exported simulation results."""
+
+__version__ = "0.1.0.dev1"

reactra/artifacts.py

@@ -0,0 +1,41 @@
+"""Exact artifact identity and publication to new local paths."""
+
+import hashlib
+import os
+import re
+import tempfile
+from contextlib import contextmanager
+from pathlib import Path
+
+
+def fingerprint(path: str | Path, *, expected_sha256=None) -> dict:
+    if expected_sha256 is not None and not re.fullmatch(r"[0-9a-fA-F]{64}", expected_sha256):
+        raise ValueError("Expected SHA-256 must contain exactly 64 hexadecimal characters")
+    digest = hashlib.sha256()
+    size = 0
+    with Path(path).open("rb") as stream:
+        while chunk := stream.read(1024 * 1024):
+            size += len(chunk)
+            digest.update(chunk)
+    actual = digest.hexdigest()
+    result = {"path": str(Path(path)), "byte_count": size, "sha256": actual}
+    if expected_sha256 is not None:
+        result["matches"] = actual == expected_sha256.lower()
+    return result
+
+
+@contextmanager
+def new_output(path: str | Path):
+    """Publish a completed temporary file without overwriting an existing path."""
+    destination = Path(path)
+    if destination.exists() or destination.is_symlink():
+        raise FileExistsError(f"Output already exists: {destination}")
+    descriptor, temporary = tempfile.mkstemp(
+        prefix=".reactra-", suffix=destination.suffix, dir=destination.parent
+    )
+    os.close(descriptor)
+    try:
+        yield Path(temporary)
+        os.link(temporary, destination)
+    finally:
+        Path(temporary).unlink(missing_ok=True)

reactra/cli.py

@@ -0,0 +1,108 @@
+"""Command-line tools for exported results, independent of the private engine."""
+
+import argparse
+import csv
+import json
+import sys
+from pathlib import Path
+
+from reactra import __version__
+from reactra.artifacts import fingerprint, new_output
+from reactra.colvar import iter_colvar, select_columns, summarize
+
+
+def export_csv(source, output, columns=None):
+    with new_output(output) as temporary:
+        with temporary.open("w", newline="", encoding="utf-8") as stream:
+            writer = csv.writer(stream)
+            selected = None
+            for row in iter_colvar(source):
+                if selected is None:
+                    selected = select_columns(row, columns)
+                    writer.writerow(selected)
+                writer.writerow(row[name] for name in selected)
+    return {"output": str(output), "columns": list(selected)}
+
+
+def plot_trace(source, output, x, ys, stride=1):
+    if stride < 1:
+        raise ValueError("Plot stride must be positive")
+    if Path(output).suffix.lower() not in (".png", ".svg", ".pdf"):
+        raise ValueError("Plot output must end in .png, .svg, or .pdf")
+    try:
+        import matplotlib
+
+        matplotlib.use("Agg")
+        import matplotlib.pyplot as plt
+    except ImportError as error:
+        raise ValueError("Plotting requires: python -m pip install 'reactra[plot]'") from error
+    selected = None
+    values = []
+    rows = 0
+    for index, row in enumerate(iter_colvar(source)):
+        if selected is None:
+            selected = select_columns(row, [x, *ys])
+        rows += 1
+        if index % stride == 0:
+            values.append(tuple(row[name] for name in selected))
+    figure, axes = plt.subplots(
+        len(ys), 1, sharex=True, squeeze=False, figsize=(8, 2.8 * len(ys)), layout="constrained"
+    )
+    try:
+        for column, axis in enumerate(axes[:, 0], 1):
+            axis.plot([row[0] for row in values], [row[column] for row in values], linewidth=1)
+            axis.set_ylabel(ys[column - 1])
+            axis.grid(alpha=0.2)
+        axes[-1, 0].set_xlabel(x + " (recorded units)")
+        figure.suptitle("Recorded simulation traces")
+        with new_output(output) as temporary:
+            figure.savefig(temporary)
+    finally:
+        plt.close(figure)
+    return {"output": str(output), "rows": rows, "plotted_rows": len(values), "stride": stride}
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(description="Reactra public simulation-result tools")
+    parser.add_argument("--version", action="version", version=__version__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    summary = commands.add_parser("summary", help="Summarize a PLUMED/COLVAR numeric table")
+    summary.add_argument("source", type=Path)
+    summary.add_argument("--columns", nargs="+")
+    summary.add_argument("--time-column", default="time")
+    export = commands.add_parser("export-csv", help="Export selected COLVAR columns to a new CSV")
+    export.add_argument("source", type=Path)
+    export.add_argument("--columns", nargs="+")
+    export.add_argument("--output", type=Path, required=True)
+    plot = commands.add_parser("plot", help="Plot recorded columns; no free-energy reconstruction")
+    plot.add_argument("source", type=Path)
+    plot.add_argument("--x", default="time")
+    plot.add_argument("--y", nargs="+", required=True)
+    plot.add_argument("--stride", type=int, default=1)
+    plot.add_argument("--output", type=Path, required=True)
+    digest = commands.add_parser("fingerprint", help="Hash exact artifact bytes, optionally verify")
+    digest.add_argument("source", type=Path)
+    digest.add_argument("--sha256")
+    return parser
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "summary":
+            result = summarize(args.source, columns=args.columns, time_column=args.time_column)
+        elif args.command == "export-csv":
+            result = export_csv(args.source, args.output, args.columns)
+        elif args.command == "plot":
+            result = plot_trace(args.source, args.output, args.x, args.y, args.stride)
+        else:
+            result = fingerprint(args.source, expected_sha256=args.sha256)
+        print(json.dumps(result, indent=2, allow_nan=False))
+        return 0 if result.get("matches", True) else 1
+    except (OSError, ValueError) as error:
+        print(json.dumps({"error": str(error)}), file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

reactra/colvar.py

@@ -0,0 +1,124 @@
+"""Strict, streaming access to PLUMED text tables; no simulation dependencies."""
+
+import math
+from pathlib import Path
+
+
+def iter_colvar(path: str | Path):
+    """Yield numeric rows by field name, refusing missing or changing schemas.
+
+    Identical repeated FIELDS headers are accepted (for concatenated chunks).
+    No sorting, deduplication, unit conversion, or periodic unwrapping occurs.
+    """
+    fields = None
+    count = 0
+    with Path(path).open(encoding="utf-8") as stream:
+        for line_number, line in enumerate(stream, 1):
+            tokens = line.split()
+            if not tokens:
+                continue
+            if tokens[:2] == ["#!", "FIELDS"]:
+                declared = tuple(tokens[2:])
+                if not declared or len(set(declared)) != len(declared):
+                    raise ValueError(f"Line {line_number}: FIELDS must be nonempty and unique")
+                if fields is not None and fields != declared:
+                    raise ValueError(f"Line {line_number}: FIELDS changed within the file")
+                fields = declared
+                continue
+            if tokens[0].startswith("#"):
+                continue
+            if fields is None:
+                raise ValueError(f"Line {line_number}: data precedes the FIELDS header")
+            if len(tokens) != len(fields):
+                raise ValueError(f"Line {line_number}: expected {len(fields)} numeric values")
+            try:
+                values = tuple(float(token) for token in tokens)
+            except ValueError as error:
+                raise ValueError(f"Line {line_number}: invalid numeric value") from error
+            if not all(math.isfinite(value) for value in values):
+                raise ValueError(f"Line {line_number}: nonfinite numeric value")
+            count += 1
+            yield dict(zip(fields, values, strict=True))
+    if not count:
+        raise ValueError("COLVAR contains no data rows")
+
+
+def select_columns(row, columns):
+    selected = tuple(columns) if columns is not None else tuple(row)
+    if not selected or len(set(selected)) != len(selected):
+        raise ValueError("Selected columns must be nonempty and unique")
+    missing = set(selected) - row.keys()
+    if missing:
+        raise ValueError(f"Unknown columns: {', '.join(sorted(missing))}")
+    return selected
+
+
+def summarize(path: str | Path, *, columns=None, time_column="time") -> dict:
+    """Compute linear population statistics in one pass and report time anomalies.
+
+    Circular CVs need circular analysis; these statistics intentionally do not
+    infer periodicity, units, reaction basins, convergence, or free energies.
+    """
+    statistics = {}
+    count = 0
+    previous_time = None
+    time = None
+    for row in iter_colvar(path):
+        if not count:
+            selected = select_columns(row, columns)
+            statistics = {
+                name: {
+                    "first": row[name],
+                    "min": row[name],
+                    "max": row[name],
+                    "mean": 0.0,
+                    "m2": 0.0,
+                }
+                for name in selected
+            }
+            if time_column in row:
+                time = {
+                    "column": time_column,
+                    "first": row[time_column],
+                    "last": row[time_column],
+                    "repeated_steps": 0,
+                    "backward_steps": 0,
+                }
+            elif time_column != "time":
+                raise ValueError(f"Unknown time column: {time_column}")
+        count += 1
+        for name, stats in statistics.items():
+            value = row[name]
+            delta = value - stats["mean"]
+            stats["mean"] += delta / count
+            stats["m2"] += delta * (value - stats["mean"])
+            stats["min"] = min(stats["min"], value)
+            stats["max"] = max(stats["max"], value)
+            stats["last"] = value
+        if time is not None:
+            current = row[time_column]
+            if previous_time is not None:
+                time["repeated_steps"] += current == previous_time
+                time["backward_steps"] += current < previous_time
+            time["last"] = current
+            previous_time = current
+    for stats in statistics.values():
+        if not all(math.isfinite(value) for value in stats.values()):
+            raise ValueError("Numeric range exceeds supported summary precision")
+        stats["std_population"] = math.sqrt(max(0.0, stats.pop("m2") / count))
+        if not all(math.isfinite(value) for value in stats.values()):
+            raise ValueError("Numeric range exceeds supported summary precision")
+    if time is not None:
+        span = time["last"] - time["first"]
+        if not math.isfinite(span):
+            raise ValueError("Time range exceeds supported summary precision")
+        time["last_minus_first"] = span
+        time["strictly_increasing"] = not (time["repeated_steps"] or time["backward_steps"])
+    return {
+        "source": str(Path(path)),
+        "rows": count,
+        "columns": statistics,
+        "time": time,
+        "units": "as recorded; not inferred",
+        "statistics": "linear; no periodic unwrapping or free-energy estimation",
+    }

reactra-0.1.0.dev1.dist-info/METADATA

@@ -0,0 +1,109 @@
+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
+```

reactra-0.1.0.dev1.dist-info/RECORD

@@ -0,0 +1,8 @@
+reactra/__init__.py,sha256=CRMxutilLajo4gtuEyxcxFosK3_Bv8crYK6E-6oserk,88
+reactra/artifacts.py,sha256=rbnGBWbIYYPgXLAscl47yFNArtgl2NhIjDqdvBfjkvY,1447
+reactra/cli.py,sha256=jmKSQad4_aafH9twXOg0CrzKtQ3l5ZykTxzHWD6lBQ8,4511
+reactra/colvar.py,sha256=amNlPyTLzqOvtvXpjrpeBQJbRkU_7tylLqhePmtDZfI,5239
+reactra-0.1.0.dev1.dist-info/METADATA,sha256=sTvLe-v7wC47NzKOrPXPXvausVuWRFZAhlhhNEqXdxM,4178
+reactra-0.1.0.dev1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+reactra-0.1.0.dev1.dist-info/entry_points.txt,sha256=zjHINyb31gn8TwkzQAowE1gYEyMBlzHk-N148pR0cfo,45
+reactra-0.1.0.dev1.dist-info/RECORD,,

reactra-0.1.0.dev1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

reactra-0.1.0.dev1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+reactra = reactra.cli:main