124 lines
3.7 KiB
Markdown
124 lines
3.7 KiB
Markdown
|
# 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.
|