Metadata-Version: 2.1
Name: dpastra
Version: 0.1.2
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

Ask your deployment provider for the HTTPS base URL and API key, replace the
placeholders below, and run the packaged demo without editing any source code:

```bash
export DPASTRA_BASE_URL="https://your-deployment.example"
export DPASTRA_API_KEY="replace-with-your-api-key"
pip install 'dpastra[watch]'
python -m dpastra.demo
```

The demo submits a 13-atom nonperiodic Cu cluster to `omat24-dpa4c-nano`, gives
it Maxwell-Boltzmann velocities at 800 K, and runs 300 Langevin steps with a
1 fs timestep. It watches the live run and downloads the authoritative
trajectory after success. DPAstra freezes the resolved exact model revision in
the durable run record; streamed frames remain previews.

## 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).
