Metadata-Version: 2.1
Name: dpastra
Version: 0.1.1
Summary: Cloud-native, ASE-compatible molecular dynamics sessions powered by DPA potentials
Author: DPAstra contributors
License: Apache-2.0
Project-URL: Source, https://github.com/iProzd/dpastra
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ase<4,>=3.26
Requires-Dist: httpx<1,>=0.28
Requires-Dist: numpy<3,>=2
Requires-Dist: pydantic<3,>=2.11
Provides-Extra: arrow
Requires-Dist: pyarrow<22,>=21; extra == "arrow"
Provides-Extra: control-postgres
Requires-Dist: psycopg[binary]<4,>=3.2; extra == "control-postgres"
Provides-Extra: dev
Requires-Dist: fastapi<1,>=0.116; extra == "dev"
Requires-Dist: mypy<2,>=1.17; extra == "dev"
Requires-Dist: packaging<27,>=25; extra == "dev"
Requires-Dist: pytest<9,>=8.4; extra == "dev"
Requires-Dist: pytest-asyncio<2,>=1.1; extra == "dev"
Requires-Dist: psycopg[binary]<4,>=3.2; extra == "dev"
Requires-Dist: ruff<1,>=0.12; extra == "dev"
Requires-Dist: setuptools>=75; extra == "dev"
Requires-Dist: uvicorn<1,>=0.35; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: zstandard<1,>=0.25; extra == "dev"
Provides-Extra: jupyter
Requires-Dist: anywidget<0.12,>=0.11; extra == "jupyter"
Requires-Dist: ipywidgets<9,>=8.1; extra == "jupyter"
Requires-Dist: rich<15,>=13.9; extra == "jupyter"
Provides-Extra: release
Requires-Dist: packaging<27,>=25; extra == "release"
Provides-Extra: server
Requires-Dist: fastapi<1,>=0.116; extra == "server"
Requires-Dist: uvicorn<1,>=0.35; extra == "server"
Provides-Extra: server-postgres
Requires-Dist: fastapi<1,>=0.116; extra == "server-postgres"
Requires-Dist: psycopg[binary]<4,>=3.2; extra == "server-postgres"
Requires-Dist: uvicorn<1,>=0.35; extra == "server-postgres"
Provides-Extra: watch
Requires-Dist: rich<15,>=13.9; extra == "watch"
Provides-Extra: worker-ase
Provides-Extra: worker-base-producer
Requires-Dist: packaging<27,>=25; extra == "worker-base-producer"
Requires-Dist: zstandard<1,>=0.25; extra == "worker-base-producer"
Provides-Extra: worker-dpa4

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/iProzd/dpastra/main/docs/assets/brand/dpastra-banner-dark.png">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/iProzd/dpastra/main/docs/assets/brand/dpastra-banner.png">
    <img src="https://raw.githubusercontent.com/iProzd/dpastra/main/docs/assets/brand/dpastra-banner.png" width="780" alt="DPAstra orbital star wordmark and streamed trajectory">
  </picture>
</p>

<p align="center">
  <strong>English</strong> · <a href="README.zh-CN.md">简体中文</a>
</p>

<h1 align="center">Molecular Dynamics, One API Away.</h1>

<p align="center">
  <strong>DPAstra = DPA + <em>astra</em> (“stars”).</strong><br>
  <em>DPA-native. API-first. Built for frontier MLIPs.</em>
</p>

<p align="center">
  <a href="https://github.com/iProzd/dpastra/actions/workflows/ci.yml"><img src="https://github.com/iProzd/dpastra/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <img src="https://img.shields.io/badge/status-research_preview-7c3aed" alt="Research preview">
</p>

## Run Molecular Dynamics Through an LLM-Style API

**The destination: interact from a local Python notebook, run molecular dynamics with 10M+ atoms in the cloud, and stream live thermodynamics and trajectory previews—all through one API.**

LLM APIs let researchers call frontier models without operating the inference stack. DPAstra applies the same abstraction to stateful molecular dynamics: scientists declare a potential, atoms, and a simulation protocol; qualified workers own the accelerator runtime and the complete MD session.

DPAstra is an independent API-first layer built to serve **DPA models and other frontier MLIPs**, designed around [**DeePMD-kit**](https://github.com/deepmodeling/deepmd-kit) execution interfaces and the open [**DeepModeling**](https://deepmodeling.com/) ecosystem.

## Install

> **Research Preview.** The default PyPI install contains the client SDK only.
> For source development and local execution, see the
> [development guide](docs/current-development.md).

```bash
pip install dpastra
```

## Models

| Model | Size | API model ID |
|---|---|---|
| DPA4C | `nano` | `omat24-dpa4c-nano` |
| DPA4 | — | — |

The API model ID is a human-readable catalog alias, not an authentication
credential. Users submit that ID; the
service resolves it to one exact immutable model revision before the run is
persisted. Advanced callers can optionally assert `model_revision`, while the
ordinary model list and submission path stay digest-free. Catalog IDs may
change before the first public release. `—` means no DPAstra-qualified entry.

> [!WARNING]
> **Research Preview.** The API and qualified model catalog may change before
> the first public release. A deployment provider supplies the HTTPS base URL,
> API key, and models available to each user. Model availability is not proof of
> scientific accuracy or production convergence for a particular system.

<sub>Scale note: 10M+ atom cloud MD depends on future qualified LAMMPS/Kokkos
and multi-GPU fleet backends; it is not a current validated capability.</sub>

## Use

> [!WARNING]
> The API is under active development. This example shows the current intended
> SDK shape and may change before release.

Ask your deployment provider for `DPASTRA_BASE_URL` and `DPASTRA_API_KEY`, then
keep both values in your environment rather than in a notebook or script. The
SDK has no default service URL. Install the optional terminal dashboard with
`pip install 'dpastra[watch]'` before calling `run.watch()`.

```python
import os

from ase.build import bulk
from dpastra import Client, MD

atoms = bulk("Cu", cubic=True)

try:
    client = Client(
        os.environ["DPASTRA_BASE_URL"],
        api_key=os.environ["DPASTRA_API_KEY"],
    )
except KeyError as error:
    raise SystemExit(f"Set {error.args[0]} before connecting to DPAstra") from None

with client:
    run = client.md.submit(
        atoms,
        model="omat24-dpa4c-nano",
        dynamics=MD.verlet(timestep_fs=0.1),
        velocity_initialization=MD.zero_velocities(),
        steps=4,
        checkpoint_every=2,
        store_every=1,
        thermo_every=1,
        stream_every=1,
    )

    run.watch()
    run.download_artifact("trajectory", "trajectory.traj")
```

The deployment operator publishes the endpoint, credential, and available
catalog. Users can discover model IDs with `client.models()` and select one for a
run. DPAstra freezes the resolved exact revision in the durable run record;
streamed frames are previews, while the downloaded trajectory is the
authoritative result.

## Documentation

- [MD parameters](docs/md-parameters.md) — constant-temperature setup,
  timestep, velocities, constraints, cadence, and planned LAMMPS mappings.
- [Watch a run](docs/watch.md) — terminal and notebook previews, with the
  authoritative trajectory downloaded after completion.
- [Development guide](docs/current-development.md) — current source setup and
  local execution.
- [Scientific contract](docs/scientific-contract.md) — units, ensembles,
  cadence, and supported boundaries.
- [Architecture](docs/architecture.md) — control plane, workers, sessions, and
  artifacts.
- [Product plan](docs/product-plan.md) — evidence-gated development direction.

DPAstra is an independent Research Preview, not an official DeepModeling
project. It is licensed under the [Apache License 2.0](LICENSE).
