notata#

Structured filesystem logging for scientific runs. Explicit. Reproducible. Grep-friendly.

Each Logbook creates a dedicated run directory that stores parameters, arrays, plots, artifacts, metadata, and a timestamped log. It’s designed to make scientific and numerical experiments fully transparent, auditable, and filesystem-native — without introducing database overhead or hidden state.

Why “notata”?#

Notata is Latin for “notes,” “annotations,” or “marked things.” The name reflects the library’s purpose: to record, organize, and preserve the essential context of computational runs — clearly and permanently.

Motivation#

In scientific computing, reproducibility is often undermined by ad hoc scripts, manual logging, or missing metadata. notata addresses this by enforcing a structured, uniform layout for saving experiment state — logs, parameters, arrays, plots, and artifacts — in plain files and directories.

Many existing tracking libraries (like TensorBoard [1], Weights & Biases [2], MLflow [3] and others [4], [5], [6], [7]) are excellent for machine learning workflows, but often:

Impose heavier dependencies and dashboards
Emphasize metrics, models, and visualizations tied to ML
Abstract away the underlying filesystem

notata is different: it’s minimal by design, and built for scientists and engineers who want to log structured data from simulations, numerical solvers, or parameter sweeps — not just train models.

It focuses on clarity over complexity, file-based organization, and human-readability — so any other scientist can inspect or reuse your results directly, without extra tooling.

If, however, you need to visualize or explore runs interactively, for example, inspecting logs, viewing saved arrays, or browsing plots, a companion tool, notata-view, is planned.

It will provide a lightweight web-based dashboard for navigating notata run directories, without introducing any server dependencies, cloud backends, or vendor lock-in. The goal is to offer convenience without compromise, optional tooling built on top of explicit, transparent filesystem structure.

Use Cases#

Simulation runs with changing parameters.
Parameter sweeps or grid searches.
Long-running numerical experiments.
Teaching or sharing reproducible computational workflows.
Auditable research pipelines that don’t rely on external platforms.

notata makes your filesystem the database — with structure and discipline.

Installation#

pip install notata

Quick Example#

Here’s a quick example of how to use notata:

from notata import Logbook, LogReader
import numpy as np

# Log a single run
with Logbook("oscillator", params={"omega": 2.0, "dt": 0.01}) as log:
    x = np.linspace(0, 10, 100)
    y = np.sin(2 * np.pi * x)
    log.array("trajectory", y)
    log.json("final_state", {"max_y": float(y.max())})

# Access the logged run
reader = LogReader("outputs/log_oscillator")
print("Run ID:", reader.run_id)
print("Metadata:", reader.meta)
print("Parameters:", reader.params)
trajectory = reader.load_array("trajectory")
print("Trajectory array:", trajectory)

This demonstrates logging structured data and accessing it programmatically.

Project Info#

GitHub
PyPI

Citation#

If you use notata in your research or publications, please consider citing it:

@software{notata_2025,
  author  = {Albert Alonso},
  title   = {notata: Structured Filesystem Logging for Scientific Runs},
  url     = {https://github.com/alonfnt/notata},
  version = {0.1.0},
  year    = {2025}
}

License#

MIT License

notata

Contents