# GRAY

## beam-tracing code for EC waves

GRAY is a beam-tracing code for Electron Cyclotron (EC) waves in a tokamak.
It is based on the complex eikonal theory (quasi-optics), which can accurately
describe the propagation of a Gaussian beam, diffraction effects included.

In addition, power absorption and current drive are computed using the fully
relativistic  dispersion relation and a neoclassical response function,
respectively.


## Documentation

The GRAY user manual is available online [here][manual].  
You can also find a PDF version of the user manual and the man pages for the
files and commands in the [release archives][releases].


## Installing

Download the latest release from [here][releases].
Some pre-compiled static binaries may be available for your platform, if not,
fetch the source archive and follow the instructions below for how to build
GRAY yourself.

[manual]: https://maxwell.eurofusion.eu/~rnhmjoj/gray/manual.html
[releases]: https://maxwell.eurofusion.eu/git/istp/gray/releases

### Building from source using Nix (recommended)

If you have the [Nix](https://nixos.org/download/#download-nix) package
manager, to build GRAY all you need to do is run `nix-build` in the source
directory. The resulting build will be linked to `./result`.

To install GRAY in your environment you can run `nix-env -i -f.`.
This will allow you to invoke `gray` (and other commands) and access the GRAY
man pages from anywhere in your system.

Note: this method is recommended because Nix will automatically fetch all
      the dependencies (at a known good version) for you and the build
      result will be reproducible.

### Building from source manually

To build GRAY from source make sure you have:

- a Fortran compiler (gfortran ≥12.0 and ifort ≥2021 tested)
- a POSIX-compatible environment (GNU and Darwin tested)
- GNU Make (≥4.4 tested)

Unpack the release archive and in the source directory run:
```shell
./configure
make
```
This will build the `gray` program in `build/bin/gray`.
You can find more configuration options by running `./configure --help`.

Finally, to install the build results, run
```shell
make install-bin
```

Note: the location where GRAY will be installed on your system can configured
      with the `--prefix` option of the `configure` script.

Note: `gray` is dynamically linked by default. If supported by your system, you
      can build a static binary using the `--enable-static` configure option.

### Building the documentation

To build the documentation (GRAY user manual and man pages) you need:

- [pandoc] (≥2.19 tested)
- [librsvg]
- a basic [Tex Live] installation (≥2022 tested)
- a [KaTeX] release archive
- [help2man]

[pandoc]: https://pandoc.org/installing.html
[TeX Live]: https://tug.org/texlive/quickinstall.html
[librsvg]: https://wiki.gnome.org/Projects/LibRsvg
[KaTeX]: https://github.com/KaTeX/KaTeX/releases
[help2man]: https://www.gnu.org/software/help2man/

Then run:
```
./configure --with-katex=/path/to/katex/archive/unpacked
make docs
```
The results will be placed in `build/share`, to install, run:
```
make install-doc
```

## Running the tests

GRAY includes a number of integration tests that are useful to check whether
your build was successful or when developing a new feature.
To run these tests you will a Python interpreter with these packages included:

- NumPy (≥1.24 and <2.0 tested)
- SciPy
- Matplotlib

To run all tests do `make check`. To test only a specific case (eg. a failed one) do:
```shell
python -m tests tests.<name>
```
The list of available tests cases is obtained with:
```shell
python -m tests --list-cases
```

Note: the `--visual` option may provide more clues into why a test case
      is failing.


## License

See the [LICENSE.md](./LICENSE.md) file.