Metadata-Version: 2.4
Name: starwave
Version: 9.0.0
Summary: Wave propagation with scalar, VRZ, VTI, elastic, Born and GSLS 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

# StarWave 9.0.0

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

This independent binary version is `9.0.0`. Its pinned private source version is
`0.1.0.dev18`, commit `fba1f496b890f2dbaf3fbb3011d39f6d723cfea1`. The source identity is also recorded
in the installed binary manifest.

## Installation and compatibility

```sh
python -m pip install ./starwave-9.0.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.

Other equations keep their own documented top-face zero/free-surface contracts.
This release adds no public `free_surface` parameter. The separate VRR extension
is not bundled and does not become `starwave.vrr`.

## Native initialization and integrity

Ordinary `import starwave` loads and binds existing bundled libraries before
returning. It does not probe CUDA availability, initialize CUDA, compile or run
propagation. Optional preparation helpers retain explicit device checks. Missing
unbuilt libraries permit explicit supported Torch use; existing invalid libraries
raise errors without silently selecting a different backend.

Scalar/VRZ/VTI core and Born use one-time ctypes loading. Their dedicated Python
files, native libraries and build metadata are excluded from runtime hashing,
including the shared verification loop reached through elastic/GSLS imports.
Core runtime loading performs no ABI, layout, semantics or capability probes.
Source/binary identity and core capability masks (scalar2D 63, scalar3D 63,
VRZ 21, VTI 127) are checked only by explicit build/artifact audits.

Elastic and GSLS preserve their audited integrity and compatibility contracts;
GSLS retains ABI 3, semantics 1 and capability mask 511. Truly shared runtime
infrastructure remains integrity-checked. Static package checks enforce the
software/platform requirements above without accessing a GPU.

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
79 runtime Python files, five 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.

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