Metadata-Version: 2.4
Name: starwave
Version: 9.1.0
Summary: Wave propagation with scalar, VRZ, VTI, elastic, Born, GSLS and VRR backends
Requires-Python: >=3.10,<3.13
Requires-Dist: torch>=2.5,<2.6
Requires-Dist: numpy>=1.23
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Scientific/Engineering :: Physics
License-File: _deepwave__LICENSE.Deepwave.txt
License-File: _deepwave_born__LICENSE.Deepwave.txt
License-File: _licenses__GCC-RUNTIME-NOTICE.txt
License-File: _licenses__LICENSE.SWEEP
License-File: _licenses__NVIDIA-CUDA-NOTICE.txt
License-File: _licenses__THIRD_PARTY_NOTICES.md
License-File: _vrr__licenses__LICENSE.Deepwave.txt
License-File: _vrr__licenses__LICENSE.SWEEP
License-File: _vrr__licenses__README.txt

# StarWave 9.1.0

StarWave provides scalar acoustic, variable-impedance acoustic (VRZ), Duveneck VTI,
elastic, scalar Born, generalized standard-linear-solid (GSLS), and VRR propagation
with PyTorch automatic differentiation.

This independent binary version is `9.1.0`. Its pinned private source version is
`0.1.0.dev19`, commit `46d32877e3336d531520a696d5f2e074e6f4ef74`. The source identity is also recorded
in the installed binary manifest.

## Installation and compatibility

```sh
python -m pip install ./starwave-9.1.0-py3-none-manylinux_2_35_x86_64.whl
```

- Linux x86_64, glibc 2.35 or newer
- Python 3.10, 3.11, or 3.12
- PyTorch >= 2.5, < 2.6; NumPy >= 1.23
- CUDA execution requires an NVIDIA GPU, a compatible installed NVIDIA driver,
  and CUDA-enabled PyTorch. CPU-only PyTorch can use explicit supported CPU routes.

The build policy uses CUDA Toolkit 11.8.89 with statically linked CUDA runtime,
SASS for SM 70/75/80/86/89/90, and compute_80 PTX. Final artifact audits check these
architectures. Architecture coverage does not establish numerical validation on
every GPU. Installation and import do not download a compiler or build native code.

## Scalar face boundaries, source gradients and observations

Scalar 2D/3D supports any subset of zero-width faces in `pml_width`, including
all-zero boundaries. Positive widths must be equal. Face order follows public
model axes: `[x_low,x_high,z_low,z_high]` or
`[x_low,x_high,y_low,y_high,z_low,z_high]`. Zero faces have fixed-zero finite-
difference ghosts and no absorbing layer or boundary buffer. Physical edge
samples remain active. The inherited truncated centered stencil is retained;
this is not a high-order odd-mirror closure or arbitrary topography.

Both scalar dimensions support first-order source-wavelet gradients. Native CUDA
supports full/boundary storage; explicit Torch supports full/checkpoint and
eager/compile. Existing source scaling, CFL/resampling and model-gradient
limitations remain: replicated model extension is frozen and its gradient is
cropped, rather than the derivative of re-replicating a perturbed edge model.

The default return remains `(receiver_records,)`. With `return_wavefield=True`,
the return is `(terminal_physical_wavefield, receiver_records)`. The terminal
field has shape `[shot, *v.shape]`, is differentiable, and follows the final
internal source update at `internal_nt * internal_dt`. Receiver records retain
their pre-update clock, so their last sample is at a different physical time.
An empty integer receiver tensor `[shot, 0, ndim]` supports terminal-only losses.

```python
empty_receivers = torch.empty((source_amplitudes.shape[0], 0, v.ndim),
                              device=v.device, dtype=torch.long)
terminal_u, records = starwave.scalar(
    v, grid_spacing, dt,
    source_amplitudes=source_amplitudes,
    source_locations=source_locations,
    receiver_locations=empty_receivers,
    pml_width=0, memory="checkpoint", backend="torch",
    return_wavefield=True,
)
loss = (terminal_u - target_wavefield).square().mean()
loss.backward()
```

`forward_callback` receives detached, independently cloned, read-only physical
snapshots. `callback_frequency` is a positive integer measured in user samples;
callbacks run after each requested interval and at the final step, never at the
initial time or again during checkpoint backward replay. Callback snapshots are
for diagnostics and visualization. They are not differentiable loss outputs;
use `return_wavefield=True` for terminal objectives. The terminal field alone
is not a complete restart state because previous time levels and CPML memories
are not returned.

## Other equations and backend scope

- VRZ and VTI retain their own CUDA full/boundary and Torch full/checkpoint
  routes, boundary rules, gradients and stream restrictions. Scalar per-face
  behavior is not generalized to them.
- Elastic retains its private Deepwave-derived CPU/CUDA implementation, CUDA
  full/boundary, and Torch full/checkpoint. Public material inputs are lambda,
  mu and buoyancy; use `starwave.common` for explicit conversions.
- Born: `starwave.scalar_born` and `starwave.ScalarBorn`, 1D/2D/3D, velocity
  perturbation `scatter = delta v` in m/s. Native CUDA full/boundary, native CPU
  full, and Torch CPU/CUDA full/checkpoint eager/compile. No MPS support.
- GSLS: 2D, fixed density and first-order gradients, full/checkpoint on native
  CPU/CUDA and Torch routes. No boundary storage, 3D GSLS or density gradients.

VRR is integrated as `starwave.vrr` and `starwave.vrr_reference`. Its native CUDA
library is bundled, with explicit Torch routes retained. Each equation retains
its own documented boundary, memory, gradient and backend limitations.

## Native initialization

Ordinary `import starwave` loads and binds existing bundled libraries. It does
not download a compiler or compile native code. Runtime hash, ABI version,
semantics version and package-version gates are absent. Artifact hashes and
native symbol contracts are checked separately during release auditing.
Scientific input validation and explicit backend/device requirements remain.

Restart Python or the notebook kernel after updating Python or native files.
Do not mix files from different wheels or source builds. The wheel contains
87 runtime Python files, six scientific native libraries and one renamed
OpenMP runtime. It excludes C/C++/CUDA sources and headers, build tools, notebooks,
tests, user data, private utilities and the unused elastic vp/vs/rho reference.
The historical `starwave._vrr.build` module retains loading helpers only.

## Validation boundaries

Compilation, ELF compatibility, clean installation, import-time loading,
CPU/reference checks, actual GPU numerical/gradient validation, multiple-GPU
execution, and long-running inversion are separate evidence categories.
Compilation or successful import does not establish GPU numerical correctness.
This wheel makes no universal GPU, multiple-GPU, MPS, long-time stability or
performance acceptance claim. Publication status and exact executed validation
belong to the release's accompanying receipt.

## Licensing and third-party notices

The project owner has not selected an overall project license. This distribution
makes no overall MIT license grant. It preserves applicable SWEEP, Deepwave and
Born MIT notices, the complete NVIDIA CUDA notice, the full GNU GPL v3 text and
GCC Runtime Library Exception. See installed `starwave/_licenses` and the
original Deepwave license files in `starwave/_deepwave` and
`starwave/_deepwave_born`.

Verbatim historical notices may describe earlier development or distribution
scopes. They remain provenance and do not replace the release's separate
publication record or create an overall project license.
