Acquirium

A Data-Metadata Framework for Water Treatment Plants

Acquirium is a framework for storing, managing, querying, and integrating data and metadata for water treatment systems. It combines knowledge graphs and time series data to support analysis, monitoring, and experimentation.

Installation

From PyPI:

pip install acquirium

Optional extras for specific drivers:

pip install "acquirium[mqtt]"       # MQTT ingestion driver
pip install "acquirium[xlsx]"       # Excel ingestion driver
pip install "acquirium[watertap]"   # WaterTAP simulation driver

Or with uv:

uv pip install acquirium

For development from a clone:

git clone https://github.com/DataDrivenCPS/acquirium.git
cd acquirium
uv sync

Quickstart

The easiest way to experiment with acquirium is through an example. We strongly recommend following the steps in the WaterTAP readme. WaterTAP is a simulation tool with an acquirium integration; following the steps there runs acquirium as if it were connected to a live plant, generating physically realistic data you can query and build applications on.

The server and its configured drivers start from one command:

acquirium server --config acquirium.toml

A sample acquirium.toml is included at the repository root. By default everything is stored on local disk (an embedded Oxigraph RDF store and a DuckDB file under data_dir); no external services are required. The first start builds the text-resolution indexes and can take 5-10 minutes; later starts reuse the cache. The server is intentionally one process because it owns the embedded graph store. materialization_workers bounds concurrent transformation execution through the server's in-process worker pool; incremental materialization supports both DuckDB and TimescaleDB backends.

Querying is a Python client:

from acquirium import Acquirium

acq = Acquirium(server_url="127.0.0.1", server_port=8000)
acq.query().entity("pump").measurement(quantity_kind="pressure").dataframe(shape="wide")

Documentation

The guides live in docs/, organized as tutorials, how-to guides, reference and explanation.

Start here — learning by doing, on the WaterTAP seawater-ro model:

How-to guides — one task each: start from a script, load a plant model, explore a model, debug a query, insert data, write an app, run the server, resolve text to URIs.

Reference — facts, no narrative: client API, drivers, apps, server configuration, HTTP API, glossary.

Explanation — why things are the way they are: the query model, values and units, why drivers, why apps use recomputed windows, the data stream lifecycle, text resolution, server internals, graph backend.

Docker stack (optional)

A compose.yaml is provided for an all-in-one local stack (Acquirium + TimescaleDB + Grafana):

make up                              # start
make up ACQUIRIUM_RECREATE=true      # wipe data + start
make down                            # stop

By default each Docker run resets the system. To preserve data across runs, set ACQUIRIUM_RECREATE=false in compose.yaml.

WaterTAP integration

The watertap extra installs the Python packages for the built-in WaterTAP driver, plus a one-time install of native solver extensions:

pip install "acquirium[watertap]"
idaes get-extensions                        # native IDAES/IPOPT solver binaries
# with uv: uv sync --extra watertap && uv run idaes get-extensions
acquirium server --config deployments/WATERTAP/scripts/acquirium.toml

The WaterTAP deployment readme covers the models, the data generator, and the example notebooks under notebooks/watertap/.

Text resolution

Free text anywhere in the API (class names, units, quantity kinds) is matched to ontology URIs by embedding similarity, using two indexes built from the bundled ontologies at server start. See the resolution guide.

Tests

uv run pytest tests/unit     # unit tests only (or: make unit-test)
make test                    # full suite (Docker required)

Status

Acquirium is under active development. Planned work is tracked in improvements.md. Bug reports and feature requests are welcome — please open an issue.