Skip to main content

naw

naw logs machine-learning time-series metrics to a compressed file on disk, and gives you a CLI to read them back.

It is two things in one package:

  • a storage library (naw.rtsdb) that writes typed, columnar, compressed rows to a single .rtsdb file, and reads them back — including while the file is still being written;
  • a wandb-compatible façade (naw.wandb) so that code already instrumented with wandb.init() / run.log() keeps working with nothing but an import change.

Full documentation: https://utrain.gitlabpages.inria.fr/naw/latest/

Installation

$ pip install naw          # or: uv add naw

naw requires Python 3.10 or newer and pulls in three small dependencies (argcomplete, pyyaml, tabulate) — no NumPy. The plot and heatmap subcommands render through uniplot and matplotlib, which are not installed by default; get them with the plot extra:

$ pip install "naw[plot]"   # or: uv add "naw[plot]"

Log a run

import naw.wandb as wandb

run = wandb.init(project="demo", config={"lr": 3e-4})
for step in range(1000):
    run.log({"loss": loss})
run.finish()

init() creates <dir>/wandb/<project>/<id>.rtsdb. A run that is never finished is still readable — you just lose the summary.

init() also starts a background monitor that records GPU utilization, VRAM, power draw, temperature, ECC errors and throttling — plus host CPU, memory, disk and network — every ten seconds. NVIDIA counters come from libnvidia-ml.so.1 bound directly with ctypes, and the host counters from /proc and /sys, so this adds no dependencies and degrades to whatever the machine actually has. The samples are ordinary metric rows, so every subcommand below reads them:

$ naw plot wandb/demo/<run-id>.rtsdb -x _timestamp -y system.gpu.0.powerWatts --lines

Pass monitor_system=False (or set NAW_MONITOR_SYSTEM=0) to turn it off.

Read it back

Every subcommand takes the run filename as its first argument:

Command Description
naw metadata FILE Show the run's identity, configuration and final summary.
naw metrics FILE List the metric columns present in the run and their storage types.
naw watch FILE Print metric rows as they are written, then exit when the run closes.
naw plot FILE -y METRIC Plot one metric against another (terminal, matplotlib, SVG, PNG or CSV).
naw heatmap FILE -m METRIC Render a histogram metric as a 2-D density map over time.
$ naw plot wandb/demo/<run-id>.rtsdb -y loss --lines

How it compresses

Values are grouped by column rather than by row, and each column is encoded with a scheme suited to its type: integers as a delta against the previous row then LEB128 varint, floats as an XOR against the previous row's value then a varint over the resulting bit pattern, and float16/bfloat16 in 2 bytes. A step counter that increments by one costs a single byte per row.

The writer periodically emits a sync point carrying a schema index, so a reader that opens the file mid-run can seek to the last sync point instead of replaying the whole file. That is what makes naw watch a live tail rather than a repeated full parse.

Documentation

References

The XOR-then-varint idea is the one introduced by Gorilla and refined by Chimp and Elf; naw uses varint framing rather than these papers' bit-level framing, which keeps decoding cheap and the format simple to reason about.

  • Gorilla: A fast, scalable, in-memory time series database
  • Chimp: efficient lossless floating point compression for time series databases
  • Elf: Erasing-Based Lossless Floating-Point Compression

License

MIT — see LICENSE.

Metadata

Release files for naw 0.0.12

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for naw 0.0.12
File Size Uploaded Provenance Actions
naw-0.0.12.tar.gz 53.9 kB Without provenance Details for naw-0.0.12.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for naw 0.0.12
File Actions
naw-0.0.12-py3-none-any.whl Python 3 none any Details for naw-0.0.12-py3-none-any.whl
naw-0.0.12-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl CPython 3.14 CPython 3.14 Linux glibc 2.5+ x86-64, Linux glibc 2.28+ x86-64 Details for naw-0.0.12-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
naw-0.0.12-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.5+ x86-64, Linux glibc 2.28+ x86-64 Details for naw-0.0.12-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
naw-0.0.12-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.5+ x86-64, Linux glibc 2.28+ x86-64 Details for naw-0.0.12-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
naw-0.0.12-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.5+ x86-64, Linux glibc 2.28+ x86-64 Details for naw-0.0.12-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
naw-0.0.12-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl CPython 3.10 CPython 3.10 Linux glibc 2.28+ x86-64, Linux glibc 2.5+ x86-64 Details for naw-0.0.12-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl

Total release size: 3.4 MB

Release files / naw-0.0.12.tar.gz

Download URL naw-0.0.12.tar.gz
Size 53.9 kB
Tags Source
SHA-256 checksum
How to use checksums
743fd8132bbf1176019c80727beb77282789f59664aad23e8e57bf9f934437d7
BLAKE2b-256 checksum
How to use checksums
1349583281ef38d17c70bb2ce58809ce23d641c0230870522623d312a15d8090
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / naw-0.0.12-py3-none-any.whl

Download URL naw-0.0.12-py3-none-any.whl
Size 58.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
12593e48563fa03046255d891f4d3f449c035d2626f113045e84d8b799cb2359
BLAKE2b-256 checksum
How to use checksums
93307e56403cd2afcf20afcc245a8a4cf181418467ae30f7b9fc2f0b87873eeb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / naw-0.0.12-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl

Download URL naw-0.0.12-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Size 660.3 kB
Tags CPython 3.14 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64
SHA-256 checksum
How to use checksums
400114e1d807dd68332d17c2219aa4a2371ea04f028d62854cee60f92b7f0181
BLAKE2b-256 checksum
How to use checksums
375d6719b0c1a4b49d89a520ddde5484a38574660164ec6ebadcae2d9ebcb5ff
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / naw-0.0.12-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl

Download URL naw-0.0.12-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Size 665.7 kB
Tags CPython 3.13 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64
SHA-256 checksum
How to use checksums
8f29fe34ad4cf126b76852697809bed7cdff6b51c39b2af59639c0800b8f8168
BLAKE2b-256 checksum
How to use checksums
0ae5a286f7aa8e4fa5e9b13fbf39ac493276d5e5e5807782be4e9c6cde18539f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / naw-0.0.12-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl

Download URL naw-0.0.12-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Size 675.4 kB
Tags CPython 3.12 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64
SHA-256 checksum
How to use checksums
97aa1cf48a30434db139abb1a3361a77afe0d0e62b7dcf083bb9274df6f0b9cd
BLAKE2b-256 checksum
How to use checksums
b1437b2a18138180cb9bbe72d6629513f5a6c5e5b7c1022177d4344a06916018
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / naw-0.0.12-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl

Download URL naw-0.0.12-cp311-cp311-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Size 635.7 kB
Tags CPython 3.11 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64
SHA-256 checksum
How to use checksums
e7758169237a15ef787590a3e71bda132daa2bfa5af6cc67c9f2a5f6bf649718
BLAKE2b-256 checksum
How to use checksums
429cf459d3ca7fd0a66355703b2e5676b0d5a1ecab85c0284f3e3c263dc145ea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / naw-0.0.12-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl

Download URL naw-0.0.12-cp310-cp310-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl
Size 613.2 kB
Tags CPython 3.10 Linux glibc 2.28+ x86-64 Linux glibc 2.5+ x86-64
SHA-256 checksum
How to use checksums
dbc6e6087426c1b701a9360d26dbeff5d7e47430e0176387beca06728d282e09
BLAKE2b-256 checksum
How to use checksums
b203cd261c23175560b2f8798491b054a87de383cc3a693a41ce2a9bf2ff2b06
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for naw 0.0.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page