From fda4ff8a3b4ca60e95f08f1a35093ae4fbc2cae4 Mon Sep 17 00:00:00 2001 From: Michele Guerini Rocco Date: Wed, 4 Dec 2024 16:17:41 +0100 Subject: [PATCH] README.md: finally add a README --- README.md | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..90465af --- /dev/null +++ b/README.md @@ -0,0 +1,123 @@ +# 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. +``` +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.