STOMS

STOMS is an SQLite-first immutable, provenance-first ledger for ASE structures and their numerical evaluations. The public library is stoms.atomsledger.

SQLite and PostgreSQL are supported backends; SQLite is the portable archive format. Structures, evaluations, trajectories, stored queries, and aggregations are immutable; post-ingestion tags are append-only annotations.

PostgreSQL

PostgreSQL 16 or newer is a supported operational backend. SQLite remains the sole portable archive format. Install the optional driver dependency:

uv sync --extra postgres --dev

Construct a ledger from a normal DSN and a schema it exclusively owns:

from stoms.atomsledger import AtomsLedger, PostgresRepository

ledger = AtomsLedger(
    PostgresRepository("postgresql://user:password@host/database", schema="project")
)

PostgresRepository creates and validates its tables in the selected schema. Do not share that schema with unrelated applications. Export a portable SQLite archive with ledger.export_database("archive.atomsledger", overwrite=True). See the PostgreSQL operational ledger guide for project setup and bidirectional SQLite synchronization.

Integration tests read STOMS_POSTGRES_TEST_DSN. The DSN must identify a disposable database; each test creates and drops its own schema.

Start the local PostgreSQL 16 test service with Docker (Engine + the Compose plugin):

docker compose up -d postgres
export STOMS_POSTGRES_TEST_DSN='postgresql://stoms:stoms@localhost:54329/stoms_test'
uv run pytest tests/postgres

If that fails with a permission error connecting to the Docker socket, your user cannot talk to the Docker daemon yet. Adding yourself to the docker group (sudo usermod -aG docker $USER, then a full logout/login) is the usual fix, but it does not always take effect right away; sudo docker compose up -d postgres works as a reliable fallback.

The Compose database uses in-memory storage and test-only credentials. Stop it after testing with docker compose down; do not use this service for data that must persist.

Install

Add STOMS as a dependency:

uv add stoms
# or
pip install stoms

Optional extras: stoms[postgres] and stoms[vasp].

Development setup

To work on STOMS itself:

uv sync --dev
uv run pytest

Install the optional VASP parser with:

uv sync --extra vasp --dev

Documentation

The documentation is ready for MkDocs publication:

• Overview
• Researcher quick start
• Getting started
• Use cases and boundaries
• Public API
• VASP parser
• Limitations

Serve it locally:

uv sync --group docs
uv run --group docs mkdocs serve