Metadata-Version: 2.4
Name: starwave
Version: 5.0.0
Summary: Scalar, VRZ, VTI CUDA and independent 2D/3D elastic CPU/CUDA propagation for PyTorch
License-Expression: MIT AND LicenseRef-NVIDIA-CUDA-11.8 AND (GPL-3.0-or-later WITH GCC-exception-3.1)
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE.NVIDIA-CUDA
License-File: LICENSE.GCC-RUNTIME
License-File: THIRD_PARTY_NOTICES.md
License-File: native/LICENSE.SWEEP
License-File: cpu_validation/reference/LICENSE
License-File: starwave/_deepwave/LICENSE.Deepwave.txt
Requires-Dist: torch<2.6,>=2.5
Requires-Dist: numpy>=1.23
Dynamic: license-file

# StarWave 5.0.0 binary distribution candidate

Public wheel version: 5.0.0. Independent maintained source version: 0.1.0.dev12.
The final exact private V12 commit and source-manifest hash are recorded in the
binary receipt. This candidate is not a publication or GPU-validation claim.

The wheel adds the reviewed scalar 3D six-face boundary implementation to the
V11 baseline. Scalar3D requires native semantics 2 and capability mask 15;
scalar2D, VRZ, VTI and the independent Deepwave-derived elastic backend retain
their reviewed scientific bytes. Elastic takes raw lamb, mu and buoyancy;
convert vp/vs/rho explicitly with starwave.common. Elastic uses [y,x]/[z,y,x]
axes, returns all 16/31 states and receivers, supports float32/float64 and full
CPU/CUDA storage, and provides CUDA-only boundary memory. The public
backward_callback is absent. No V10 public CFL planner or SWEEP elastic2D API is
added. Public Python scientific implementations are copied byte-for-byte from
the frozen source; only packaging paths and loader integrity checks adapt.

## Compatibility target

- Linux x86_64, glibc 2.35+; GLIBCXX <=3.4.30/CXXABI <=1.3.13 build requirements
- Python 3.10–3.12, PyTorch 2.5.x, NumPy >=1.23, preserving the prior wheel target
- CUDA 11.8.89 statically linked into both native libraries; no toolkit needed
- SASS sm70/75/80/86/89/90 plus compute80 PTX, separately checked in both libraries
- NVIDIA driver supporting the actual GPU; conservative CUDA11.8 target 520.61.05+
- Elastic CPU OpenMP enabled and its reviewed libgomp bundled; no serial fallback

These are build/install targets until the exact wheel passes the corresponding
matrix. Start GPU acceptance with PyTorch2.5.1 cu118. Compilation and host loading
do not establish GPU correctness, multi-GPU scaling, FWI convergence or speed.

## Contents and loading

The wheel contains the readable Python runtime, two precompiled native libraries,
the isolated GNU OpenMP runtime, minimal integrity metadata and required licenses.
CUDA/C/C++ sources, headers, source manifests, build programs, private reference
wrappers, tests, utils, notebooks, model data and results are excluded. No source
distribution is permitted. Imports never compile or load either native library.

Use starwave.prepare_native([0]) for scalar/VRZ/VTI and
starwave.prepare_elastic([0]) for elastic GPU work, substituting the explicitly
selected visible logical device IDs. starwave.prepare_elastic() preloads the CPU
elastic library without running a propagation. Restart Python after upgrading.
Source fingerprints remain enforced in private source checkouts. Installed wheels
verify their exact runtime subset and both binary hashes, source/release identity,
core ABI/capabilities, scalar3D entries 5/6/7 and actual elastic exports instead of looking for omitted
private source files. This is unsigned integrity, not an authenticity signature.

## Scientific and acceptance boundaries

Scalar3D uses model axes [x,y,z], integer coordinates [i,j,k], spatial orders
2/4/6/8, full or six-face boundary memory, and first-order model/source
gradients. Its raw-source VJP also supplies the velocity source-scaling chain.
Scalar2D retains its fixed-source contract; scalar3D illumination is not exposed. The inherited
scalar/VRZ/VTI PML/model-extension gradient limits remain; binary
packaging does not repair or reinterpret them. Elastic's full/boundary, callbacks,
sampling and gradient rules remain those of the exact V12 source contract.
No public GPU, DataParallel, long-running FWI or performance result is asserted
by this packaging overlay. Test reports distinguish source CPU tests, installed
wheel native CPU tests, host ABI loads, CUDA compilation and actual GPU tests.

Known inherited elastic edge case: when the model-gradient sampling schedule has
zero complete groups (the requested interval exceeds the effective available
duration), the uploaded full bridge and official Deepwave0.0.27 raise a zero-step
range ValueError. V12 deliberately retains this behavior. The proposed no-op
change is excluded; expected-failure regressions document the unresolved case.
Avoid that configuration until its tail/sampling semantics are separately reviewed.

Production-scale3D memory fit is not established. Boundary mode can still require
very large native history/workspace allocations; it does not guarantee that a
full survey or model fits a GPU. Estimate and test the actual grid, internal
steps and shots before scaling. GPU memory, speed and multi-GPU acceptance remain
separate pending measurements.
