Metadata-Version: 2.4
Name: scotty-beam-tracing
Version: 4.0.0rc1
Summary: Beam tracing for tokamak DBS diagnostics
Author: Valerian Hall-Chen
Project-URL: project, https://github.com/beam-tracing/Scotty
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numpy>=2.0
Requires-Dist: scipy>=1.13
Requires-Dist: matplotlib>=3.8
Requires-Dist: xarray>=2024.10.0
Requires-Dist: h5netcdf[h5py]
Provides-Extra: tests
Requires-Dist: pytest; extra == "tests"
Requires-Dist: pytest-timeout; extra == "tests"
Requires-Dist: pytest-xdist; extra == "tests"
Provides-Extra: docs
Requires-Dist: sphinx>=5.3; extra == "docs"
Requires-Dist: sphinx-book-theme>=1.1.0; extra == "docs"
Dynamic: license-file

Scotty
======

Beam tracing for tokamak DBS diagnostics


Scotty v3 and v4
----------------

**Scotty v4 is at its first release candidate, 4.0.0rc1.** It is the version on
the `master` branch. The rc freezes the interface (argument names and defaults,
what the inputs mean, the output variables), so scripts written for it should
keep working in 4.0.0; only fixes that leave the interface alone go in before
then. Some of v3's features haven't been ported yet. Until 4.0.0 is released,
v3 is the stable line: use it for published work, or anything you need to
reproduce later. Please try v4 and report problems at
https://github.com/beam-tracing/Scotty/issues.

- **v3** (stable, the released version): beam tracing in cylindrical coordinates
  (R, ζ, Z). The latest release is 3.2.0.
- **v4** (release candidate 4.0.0rc1): the same beam model,
  with a choice of cylindrical or Cartesian (X, Y, Z) coordinates
  (`geometry="cylindrical"` or `"cartesian"`). Outputs are given in both. It has
  been checked against v3 on the test suite and on DIII-D, MAST-U and MAST
  cases. Its known differences from v3 (see the release notes in the
  documentation, `docs/release_notes.rst`):
  - some arguments and output names have changed. `scotty.compat.from_v3_kwargs`
    translates v3's `beam_me_up` arguments, and `scotty.compat.quick_cutoff`
    replaces v3's `quick_run`;
  - `launch_flag` replaces v3's `vacuumLaunch_flag` and
    `vacuum_propagation_flag`: `"vacuum_analytic"` (analytic propagation to the
    plasma boundary, then `Psi_BC_flag`; v3's `vacuum_propagation_flag=True`),
    `"vacuum_numerical"` (the solvers start at the antenna; v3's
    `vacuum_propagation_flag=False`) or `"plasma"`;
  - a plasma launch (`launch_flag="plasma"`, v3's `vacuumLaunch_flag=False`)
    checks that the launch point is inside the plasma and that K satisfies the
    dispersion relation, and takes K and Ψ in Cartesian components. With no
    launched beam, `filterfun_b` and `filterfun_all` are NaN;
  - `Psi_BC_flag` is `"continuous"`, `"discontinuous"` or `None`; v3's
    deprecated `True` and `False` raise an error. `Psi_BC_flag=None` (v3's
    default) checks that the density is zero and flat at the plasma edge, and
    raises an error otherwise;
  - the localisation is called the filter function: v3's `loc_*` are v4's
    `filter_*`;
  - the default spatial finite-difference step (`delta_R`, `delta_Z`, ...) is
    1e-5 (v3: 1e-4), the default solver tolerances are `rtol=1e-4`,
    `atol=1e-7` (v3: 1e-3, 1e-6), and the default `len_tau` is 4002 (v3: 102);
  - not yet ported: most of v3's matplotlib plots (`scotty.plotting` has
    `plot_dispersion_relation`, `plot_poloidal_beam_path` and
    `plot_toroidal_beam_path`), the filter-function widths (`delta_l`,
    `delta_kperp1`), the GUI (`GUI/scottypygui.py`), and the `curvy_slab`
    field, which is deprecated;
  - check which version you have with `scotty.__version__`. An install from
    `master` after the rc gives a development version such as
    `4.0.0rc2.dev5+g1234abc` (from `setuptools_scm`).


Install
-------

The package to install is called `scotty-beam-tracing`, but the Python module is
just `scotty`.

**v3 (stable).** From PyPI:

```
pip install scotty-beam-tracing
```

or a specific release straight from GitHub:

```
pip install git+https://github.com/beam-tracing/Scotty@v3.2.0
```

**v4 (release candidate).** From PyPI (pip installs release candidates only
when asked to):

```
pip install scotty-beam-tracing==4.0.0rc1
```

or the latest development version, straight from GitHub:

```
pip install git+https://github.com/beam-tracing/Scotty
```

or from a local clone:

```
pip install .
```

when developing, use:

```
pip install -e .
```

Documentation
-------
https://scotty.readthedocs.io/

Background
-------
Description of the Scotty [[1]](#1), derivation of beam tracing given in Appendix A.

## References
<a id="1">[1]</a> 
Hall-Chen, V. H., Parra, F. I., & Hillesheim, J. C. (2022). 
[Beam model of Doppler backscattering](https://iopscience.iop.org/article/10.1088/1361-6587/ac57a1). 
*Plasma Physics and Controlled Fusion*, **64**(9), 095002.
