Metadata-Version: 2.4
Name: warp-simdata
Version: 0.1.0
Summary: Warp-based simulation data framework with protocol-based data model abstraction
Author: NVIDIA CORPORATION & AFFILIATES
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/NVIDIA/warp-simdata
Project-URL: Issues, https://github.com/NVIDIA/warp-simdata/issues
Project-URL: Changelog, https://github.com/NVIDIA/warp-simdata/blob/main/CHANGELOG.md
Keywords: visualization,scientific-computing,data-analysis,gpu,warp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
License-File: NOTICE.md
Requires-Dist: warp-lang>=1.12.0
Requires-Dist: numpy>=1.20.0
Provides-Extra: io
Requires-Dist: h5py>=3.0.0; extra == "io"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Requires-Dist: pytest-xdist>=3.0; extra == "test"
Requires-Dist: pytest-timeout>=2.1; extra == "test"
Requires-Dist: h5py>=3.0.0; extra == "test"
Requires-Dist: vtk>=9.0.0; extra == "test"
Provides-Extra: usd
Requires-Dist: cae-openusd-plugins>=0.1.0; extra == "usd"
Provides-Extra: dev
Requires-Dist: warp-simdata[test]; extra == "dev"
Requires-Dist: ruff>=0.14.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: bandit[toml]>=1.7.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Dynamic: license-file

<!--
SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->

# Warp SimData

Warp SimData is a Warp-native Python library for processing simulation data. Scientific data comes in many shapes and forms.
While popular standardized data models exist, simulation codes, time and again, produce data in custom formats tailored
to their specific needs. This creates a dilemma when writing data processing algorithms: either invest
significant effort converting data to a standardized model, or write bespoke implementations
for each custom format. Both approaches are time-consuming and error-prone. This project
explores whether we can avoid this trade-off altogether by providing a flexible framework
that works seamlessly across different data models.

> **Disclaimer:**
> Warp SimData is not part of the `warp-lang` package, and it is not maintained by the [NVIDIA Warp](https://nvidia.github.io/warp) core team.
> It is a Warp ecosystem library. Issues, releases, roadmap, and support are managed by the maintainers of this repository.

## Background

Warp SimData grew out of [Kit-CAE](https://github.com/NVIDIA-Omniverse/kit-cae),
where we developed Warp-based algorithms for simulation data processing. That
work was largely intended to showcase how [NVIDIA Warp](https://nvidia.github.io/warp/)
could accelerate CAE operations and how those capabilities could be integrated
into Omniverse workflows.

The algorithms are potentially useful beyond Kit-CAE, so we split them into
this standalone project. This makes it possible to use, evaluate, and develop
them without adopting the Kit and Omniverse application stack.

Warp SimData now serves both as a practical example of using Warp for simulation
data processing and as an experimental framework for applying algorithms across
heterogeneous data models. It explores whether operators can share a consistent
implementation while model-specific access is supplied through lightweight
interfaces, avoiding unnecessary data conversion and copying.

## Installation

### Requirements

- Python 3.10 or newer
- `warp-lang` 1.12.0 or newer
- NumPy 1.20.0 or newer
- An NVIDIA CUDA-capable GPU and compatible driver for CUDA execution; CPU
  execution is also supported
- Git LFS when cloning the full source tree and its test data

### From Source

```bash
git clone https://github.com/NVIDIA/warp-simdata.git
cd warp-simdata
pip install .
```

### For Developers

```bash
# Setup virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in editable mode with test dependencies
pip install -e .[test]

# Or install with all development tools (linting, formatting, type checking)
pip install -e .[dev]

# Run all tests
pytest tests/
```

See [INSTALL.md](INSTALL.md) for detailed installation instructions.

## Testing

### Quick Start

```bash
# After installing with test dependencies (pip install -e .[test])
pytest tests/
```

### Common Commands

```bash
# Run tests on CPU only (filter by device parameter)
pytest tests/ -k "[cpu]"

# Run tests on GPU only (requires CUDA)
pytest tests/ -k "[cuda]"

# Run fast tests (skip slow/VTK)
pytest tests/ -m "not slow and not vtk"

# Run with coverage report
pytest tests/ --cov=warp_simdata --cov-report=html

# Run specific operator tests
pytest tests/test_bounds.py
pytest tests/test_centroid.py

# Run in parallel (faster)
pytest tests/ -n auto

# Verbose output with full tracebacks
pytest tests/ -vv
```

Optional visualization filters can also be loaded from a source checkout in
ParaView; see the [ParaView extension instructions](extras/paraview/README.md).

## Basics

Warp SimData is based on [NVIDIA Warp](https://nvidia.github.io/warp/modules/runtime.html).
Similar to Warp, Warp SimData has two sets of APIs: one intended to be used at the *Python Scope* and
run inside the CPython interpreter, and second intended to be used at the *Kernel Scope* which,
while still written in Python, get JIT compiled to CUDA or C++ to execute on target devices
like CPU or CUDA compute.

> **CPU performance note:**
> Warp currently processes kernel work sequentially when a CPU device is the
> target. CPU execution is supported, but workloads designed for parallel
> execution may be significantly slower than expected. CPU use cases should
> become more practical when Warp supports parallelizing kernel launches across
> CPU cores.

Python scope APIs are intended for users and developers who want to use Warp SimData for specific data
processing tasks. Kernel scope APIs are for those developers who want to introduce new data models to Warp SimData
or develop operators for data processing in Warp SimData.

**API Reference:**
- [Python Scope Reference](docs/PythonAPI.md) - Complete guide for using Warp SimData operators and datasets
- [Kernel Scope Reference](docs/KernelAPI.md) - Guide for developing data models and operators
- [Element Faces Operator](docs/ElementFaces.md) - Boundary classification, CPU/CUDA implementations, memory model, and limitations
- [Iso-Surface Operator](docs/IsoSurface.md) - Single/batched interfaces, implementation, supported topology, and open work
- [Plane Slice Operator](docs/Slice.md) - Plane batching, exact preselection design, field transfer, and performance
- [OpenUSD Reference](docs/USDAPI.md) - Using `warp_simdata.usd` to convert OpenUSD scientific dataset prims into Warp SimData datasets and fields
- [Changelog](CHANGELOG.md) - Notable changes grouped by release

Common operators include bounds, element bounds/sizes, centroids, probing,
voxelization, advection, streamlines, `element_faces`, and `iso_surface`.
`element_faces` extracts volumetric faces as a surface mesh and can compact
only external faces with `external_only=True`. See the
[element-faces operator reference](docs/ElementFaces.md) for its topology
contract, device-specific classification, and resource model. `iso_surface` extracts a merged
triangular surface from a node scalar through any data model that exposes the
required neutral topology capabilities. See the
[operator reference](docs/IsoSurface.md) for its contract, implementation,
limitations, and maintained open-work list.

```python
import warp_simdata as simdata
from warp_simdata.operators import bounds, iso_surface

result = bounds.compute(dataset)
field = simdata.Field.from_array(values, simdata.AssociationType.NODE)
dataset.add_field("pressure", field)
surface = iso_surface.compute(dataset, "pressure", 0.5)
```

## OpenUSD Integration

The `warp_simdata.usd` package provides adapters from OpenUSD scientific dataset prims
to Warp SimData datasets and fields. This is the recommended path when your data is
already represented in USD through scientific schemas such as CGNS and CAE
mesh, point-cloud, EnSight, or OpenFOAM marker APIs.

The scientific schemas and native file-format plugins consumed by these
adapters are provided by
[CAE OpenUSD Plugins](https://github.com/NVIDIA-Omniverse/cae-openusd-plugins).
Refer to its [schema documentation](https://github.com/NVIDIA-Omniverse/cae-openusd-plugins/tree/main/docs/schemas)
and [Conceptual Data Mappings](https://github.com/NVIDIA-Omniverse/cae-openusd-plugins/tree/main/docs/conceptual_data_mapping)
for the authoritative USD contracts.

See the [OpenUSD Reference](docs/USDAPI.md) for supported schemas, API details,
and usage examples.

```python
import warp_simdata.usd as simusd

dataset = simusd.dataset_from_prim(prim, device="cuda:0")
fields = simusd.list_fields(prim)
pressure = simusd.field_from_prim(prim, "pressure", device="cuda:0")
```

## Contributing

This project is currently not accepting contributions.

## Releases

See [CHANGELOG.md](CHANGELOG.md) for notable changes. Release artifacts are
published through the repository's [Releases](https://github.com/NVIDIA/warp-simdata/releases)
page when available.
See the [versioning and release guide](docs/versioning.md) for supported
version forms, release branches, and tag conventions.

## Governance and Maintainers

Warp SimData is maintained by NVIDIA. See [GOVERNANCE.md](GOVERNANCE.md) and
[MAINTAINERS.md](MAINTAINERS.md).

## Security

Do not report security vulnerabilities through public GitHub issues. Follow the
private disclosure process in [SECURITY.md](SECURITY.md).

## Support

Warp SimData is an experimental project. See [SUPPORT.md](SUPPORT.md) for
support channels and response expectations.

## License

Warp SimData is licensed under the Apache License 2.0. See
[LICENSE.md](LICENSE.md) and [NOTICE.md](NOTICE.md).
