Metadata-Version: 2.1
Name: treaaams
Version: 0.4.6rc5
Summary: Derivative of treams with complex frequency support
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy >=1.23
Requires-Dist: scipy <1.17,>=1.9
Requires-Dist: tbump >=6.11.0
Requires-Dist: threadpoolctl >=3.6.0

# treaaams v0.4.6c5

A derivative of [treams](https://github.com/tfp-photonics/treams) with targeted
source-level patches to enable complex frequency evaluation.

## How it works

```
GitHub (treams vX.Y.Z)
        │  tarball download
        ▼
_build/treams_src/          ← clean upstream source
        │  patch -p1 (each file in patches/ in order)
        ▼
_build/treams_src/          ← patched source
        │  build (and publish) wheel
        ▼
install treaaams via pip/uv
```

## Prerequisites

- Python ≥ 3.10
- [uv](https://github.com/astral-sh/uv) (recommended) **or** pip
- A C compiler + `patch` utility (`apt install patch` / `brew install gpatch`)
- Cython and NumPy (installed automatically by the build backend)

## Quick start: editable install

```bash
# 1. Create a virtual environment (uv)
uv sync

# 2. Fetch upstream, apply patches, and install in editable mode
make editable

# 3. Verify
python -c "import treaaams; print(treaaams.__version__)"
```

## Adding or modifying a patch

### Workflow

```bash
# 1. Make sure you have a clean source tree
python scripts/build_patched.py --no-fetch   # skips download, resets patches

# 2. Edit the file you want to change
$EDITOR _build/treaaams_src/src/treams/_special/sph.pyx

# 3. Capture the diff as a numbered patch file
python scripts/make_patch.py src/treaaams/_special/sph.pyx \
    --name 010-custom-sph

# 4. Inspect it
cat patches/010-custom-sph.patch

# 5. Dry-run all patches to verify
make patch-dry-run

# 6. Rebuild
make editable
```

### Patch naming convention

Patches are applied **lexicographically**, so number them explicitly:

| File | Applied |
|---|---|
| `000-fix-typo.patch` | first |
| `010-override-ufunc.patch` | second |
| `020-custom-lattice.patch` | third |

## Tracking a new upstream version

Run for example
```
uv run tbump 0.4.7c1
```
To apply the patches to v0.4.7 of treams

If a patch no longer applies cleanly, `patch` will create a `.rej` file with
the rejected hunks.  Edit the patch accordingly and re-run.
