istp/gray
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity

add documentation

Browse Source
This commit is contained in:
Michele Guerini Rocco 2021-12-15 02:30:58 +01:00
parent bfbd479d20
commit 08dad4ff45
Signed by: rnhmjoj
GPG Key ID: BFBAF4C975F76450
11 changed files with 1599 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
Makefile
View File

@ -8,16 +8,20 @@
# Structure: # Structure:
# gray - top level # gray - top level
# ├── src - source code # ├── src - source code
# ├── doc - documentation
# └── build - build artifacts # └── build - build artifacts
# ├── bin - binaries # ├── bin - binaries
# ├── lib - libraries # ├── lib - libraries
# └── obj - objects # └── obj - objects
SRCDIR = src SRCDIR = src
BUILDDIR = build BUILDDIR = build
SHAREDIR = build/share
BINDIR = build/bin BINDIR = build/bin
LIBDIR = build/lib LIBDIR = build/lib
OBJDIR = build/obj OBJDIR = build/obj
DIRS = $(BINDIR) $(OBJDIR) $(LIBDIR)
# Directories that need to be created
DIRS = $(BINDIR) $(OBJDIR) $(LIBDIR) $(SHAREDIR)
## ##
## Files ## Files
@ -71,18 +75,20 @@ endif
## Targets ## Targets
## ##
.PHONY: all clean install .PHONY: all clean install docs
all: $(BINARIES) $(LIBRARIES) all: $(BINARIES) $(LIBRARIES) docs
# Remove all generated files # Remove all generated files
clean: clean:
rm -r $(BUILDDIR) rm -r $(BUILDDIR)
# Install libraries, binaries and man pages # Install libraries, binaries and documentation
install: $(BINARIES) $(LIBRARIES) doc/gray.1 install: $(BINARIES) $(LIBRARIES) doc/gray.1
install -Dm555 -t $(PREFIX)/bin $(BINDIR)/* install -Dm555 -t $(PREFIX)/bin $(BINDIR)/*
install -Dm555 -t $(PREFIX)/lib $(LIBDIR)/* install -Dm555 -t $(PREFIX)/lib $(LIBDIR)/*
install -Dm644 -t $(PREFIX)/share/doc $(SHAREDIR)/doc/manual.*
install -Dm644 -t $(PREFIX)/share/doc/res $(SHAREDIR)/doc/res/*
install -Dm644 -t $(PREFIX)/share/man/man1 doc/gray.1 install -Dm644 -t $(PREFIX)/share/man/man1 doc/gray.1
# GRAY binary # GRAY binary
@ -97,6 +103,11 @@ $(LIBGRAY).so: $(MODULES) | $(LIBDIR)
$(LIBGRAY).a($(MODULES)): | $(LIBDIR) $(LIBGRAY).a($(MODULES)): | $(LIBDIR)
$(LIBGRAY).a: $(LIBGRAY).a($(MODULES)) $(LIBGRAY).a: $(LIBGRAY).a($(MODULES))
# All documentation
docs: | $(SHAREDIR)
make -C doc
cp -t $(SHAREDIR) -r doc/build/*
# Visualise the dependency graph # Visualise the dependency graph
# Note: requires makefile2graph and graphviz # Note: requires makefile2graph and graphviz
graph.svg: Makefile graph.svg: Makefile

8
configure vendored
View File

@ -15,6 +15,7 @@ Options:
--prefix=PREFIX install files in PREFIX [/usr/local] --prefix=PREFIX install files in PREFIX [/usr/local]
--enable-static statically link programs and libraries [no] --enable-static statically link programs and libraries [no]
--disable-static dynamically link programs and libraries [yes] --disable-static dynamically link programs and libraries [yes]
--with-katex=PATH specify path to the KaTeX library [automatically downloaded]
EOF EOF
} }
@ -26,6 +27,9 @@ check() {
return $? return $?
} }
# Truncate the current configuration
: > configure.mk
# Parse command line options # Parse command line options
for arg in "$@"; do for arg in "$@"; do
case "$arg" in case "$arg" in
@ -36,6 +40,7 @@ for arg in "$@"; do
;; ;;
--enable-static) printf 'STATIC=1\n' >> configure.mk ;; --enable-static) printf 'STATIC=1\n' >> configure.mk ;;
--disable-static) ;; --disable-static) ;;
--with-katex=*) printf 'KATEX_URL==file://%s/\n' "${arg#*=}" >> configure.mk ;;
*=*) *=*)
printf '%s\n' "${arg?}" >> configure.mk printf '%s\n' "${arg?}" >> configure.mk
printf 'set %s\n' "$arg" printf 'set %s\n' "$arg"
@ -44,9 +49,6 @@ for arg in "$@"; do
esac esac
done done
# Truncate the current configuration
: > configure.mk
# Platform information # Platform information
printf 'Running on ' printf 'Running on '
case $(uname -s) in case $(uname -s) in

27
default.nix
View File

@ -8,6 +8,12 @@ let
sha256 = "1mk3s4ncfa8z8mr6vrgjh74s8dci12yam7plpc1bqgz12wld73ax"; sha256 = "1mk3s4ncfa8z8mr6vrgjh74s8dci12yam7plpc1bqgz12wld73ax";
}) {}; }) {};
# Needed for HTML manual
katex = builtins.fetchTarball {
url = "https://github.com/KaTeX/KaTeX/releases/download/v0.15.1/katex.tar.gz";
sha256 = "007nv11r0z9fz593iwzn55nc0p0wj5lpgf0k2brhs1ynmikq9gjr";
};
# Exclude this file and build artifacts # Exclude this file and build artifacts
source = builtins.filterSource source = builtins.filterSource
(path: type: (path: type:
@ -22,12 +28,31 @@ in
version = "0.1"; version = "0.1";
src = source; src = source;
nativeBuildInputs = with pkgs; [ makefile2graph graphviz gfortran ]; nativeBuildInputs = with pkgs; [
# fortran
gfortran
# debugging
makefile2graph graphviz
# documentation
pandoc haskellPackages.pandoc-crossref
(texlive.combine {
inherit (texlive) scheme-small xetex fontspec;
})
];
# fonts needed for the PDF manual
FONTCONFIG_FILE = pkgs.makeFontsConf {
fontDirectories = with pkgs; [ fira-mono libertinus ];
};
buildInputs = lib.optional static pkgs.glibc.static; buildInputs = lib.optional static pkgs.glibc.static;
hardeningDisable = [ "format" ]; hardeningDisable = [ "format" ];
configureFlags = [ configureFlags = [
(lib.enableFeature static "static") (lib.enableFeature static "static")
"--with-katex=${katex}"
"GIT_REV=${version}" "GIT_REV=${version}"
"GIT_DIRTY=" "GIT_DIRTY="
]; ];

154
doc/1.intro.md Normal file
View File

@ -0,0 +1,154 @@
---
title: GRAY user manual
author:
- D. Farina[^1]
- L. Figini[^1]
- A. Mariani[^1]
- M. Guerini Rocco[^2]
date: 'November 30, 2012. Updated: November 30, 2021'
lang: en-GB
language: english
# Bibliography
link-citations: true
citation-style: res/style.csl
reference-section-title: Bibliography
references:
- id: gray
title: 'A quasi-optical beam-tracing code for electron cyclotron
absorption and current drive: GRAY'
author:
- family: Farina
given: D.
container-title: Fusion Science and Technology
doi: 10.13182/fst07-a1494
issue: 2
issued: 2007-08
page: 154-160
publisher: Informa UK Limited
type: article-journal
volume: 52
- id: gaussian-beam
title: 'Gaussian light beams with general astigmatism'
author:
- family: Arnaud
given: J. A.
- family: Kogelnik
given: H.
container-title: Applied Optics
doi: 10.1364/ao.8.001687
issue: 8
issued: 1969-08
page: 1687
publisher: The Optical Society
type: article-journal
volume: 8
- id: cocos
title: 'Tokamak coordinate conventions: COCOS'
author:
- family: Sauter
given: O.
- family: Medvedev
given: S.Yu.
container-title: Computer Physics Communications
doi: 10.1016/j.cpc.2012.09.010
issue: 2
issued: 2013-02
page: 293-302
publisher: Elsevier BV
type: article-journal
volume: 184
- id: marushchenko
title: 'Current drive calculations with an advanced adjoint approach'
author:
- family: Marushchenko
given: N. B.
- family: Beidler
given: C. D.
- family: Maassberg
given: H.
container-title: Fusion Science and Technology
doi: 10.13182/fst55-180
issue: 2
issued: 2009-02
page: 180-187
publisher: Informa UK Limited
type: article-journal
volume: 55
- id: dispersion
title: 'Relativistic dispersion relation of electron cyclotron waves'
author:
- family: Farina
given: Daniela
container-title: Fusion Science and Technology
doi: 10.13182/fst08-a1660
issue: 1
issued: 2008-01
page: 130-138
publisher: Informa UK Limited
type: article-journal
volume: 53
- id: angles
title: ???
author:
- family: Zvonkov
given: A.
- family: Gribov
given: Y.
- family: Bindslev
given: H.
issued: 2003-3-5, 2003-4-5
# Font
mainfont: Libertinus Serif
mathfont: Libertinus Math
monofont: Fira Mono
# PDF output options
classoptions:
- a4paper
- 14pt
geometry:
- top=2cm
- bottom=2cm
# HTML output options
css: res/style.css
# pandoc-crossref options
linkReferences: true
tableEqns: true
...
[^1]: Istituto per la Scienza e Tecnologia dei Plasmi,
Consiglio Nazionale delle Ricerche
Via R. Cozzi, 53 - 20125 Milano, Italy
[^2]: Università degli Studi di Milano-Bicocca,
Piazza dell'Ateneo Nuovo, 1 - 20126, Milano
# Introduction
The beam tracing code GRAY performs the computation of the quasi-optical
propagation of a Gaussian beam of electron cyclotron waves in a general tokamak
equilibrium, and of the power absorption and driven current [@gray].
The propagation of a general astigmatic Gaussian beam is described within the
framework of the complex eikonal approach in terms of a set of "extended" rays
that allow for diffraction effects. The absorbed power and the driven current
density are computed along each ray solving the fully relativistic dispersion
relation for electron cyclotron wave and by means of the neoclassical response
function for the current.
The aim of the present note is to document the current version of the GRAY
code, by describing the main code features and listing the inputs and outputs.
To this goal in [@sec:physics] the main equations and models used in the GRAY
code to compute Gaussian beam propagation, absorption and current drive are
summarized shortly. In [@sec:io-files], the details on the code inputs and
outputs are presented.

468
doc/2.physics.md Normal file
View File

@ -0,0 +1,468 @@
# Physics {#sec:physics}
## Coordinate Reference systems
A few sets of coordinate systems are used in the code. The reference system is
the right handed cartesian orthogonal system $(x, y, z)$ with $z$ axis being
the tokamak symmetry axis. For the purpose of the physics analysis this
coordinate system may be rotated around the $z-$axis so that the $x z$ plane
contains the launching point, i.e., $z$ vertical, $x$ radially outward through
the port center, and $y$ pointing in the counter clockwise direction when
viewed from above.
In addition to the right handed cartesian orthogonal system specified above, we
introduce also a right-handed cylindrical system $(R,φ,Z)$ with transformation
from the cylindrical to the cartesian system given by $x= R\cosφ$, $y=R\sinφ$,
$z=Z$.
## Quasi-optical approximation
In the complex eikonal framework, the a solution of the wave equation for the
electric field is looked for in the form
$$
{\bf E}({\bf x},t) =
{\bf e}({\bf x}) E_0({\bf x})
e^{-i k_0 S({\bf x}) + iωt}
$$ {#eq:eikonal-ansatz}
such that it allows for Gaussian beam descriptions.
In [@eq:eikonal-ansatz], $ω$ is the real frequency, $k_0 = ω/c$ the
wavevector amplitude in vacuum, ${\bf e}({\bf x})$ the polarisation versor and
$E_0({\bf x})$ the slowly varying wave amplitude.
The function $S({\bf x})$ is the complex eikonal, $S = S_R({\bf x}) + i S_I
({\bf x})$, in which the real part $S_R({\bf x})$ is related to the beam
propagation as in the geometric optics (GO), and the imaginary part $S_I({\bf
x}) (<0)$ to the beam intensity profile shape, as it is apparent writing
[@eq:eikonal-ansatz] as
$$
{\bf E}({\bf x},t) =
{\bf e}({\bf x}) E_0({\bf x})
e^{k_0 S_I({\bf x})} e^{-i k_0 S_R({\bf x})+i ωt}
$$ {#eq:efri}
## Gaussian beams
We introduce a reference system $({\bar x},{\bar y},{\bar z})$, in which the
$\bar z$ axis is directed along the direction of propagation of the beam and
the $\bar x$ axis lies in the horizontal plane (i.e., $z=\text{const}$), and
two additional coordinate systems, $(\xi_w,\eta_w)$ and $(\xi_R,\eta_R)$ in the
$(\bar x, \bar y)$ plane, rotated by the angles $φ_w$ and $φ_R$,
respectively,
$$
\begin{aligned}
\bar x &= \xi_w \cos φ_w - \eta_w \sin φ_w
= \xi_R \cos φ_R - \eta_R \sin φ_R \\
\bar y &= \xi_w \sin φ_w + \eta_w \cos φ_w
= \xi_R \sin φ_R + \eta_R \cos φ_R
\end{aligned}
$$ {#eq:phiwr}
In the $(\xi_w,\eta_w)$ and $(\xi_R,\eta_R)$ systems, the axes are aligned
with the major and minor axes of the intensity and phase ellipses respectively,
and the general astigmatic Gaussian beam in vacuum takes the simple form
[@gaussian-beam]
$$
E ({\bf x}) \propto
\exp{\left[- \left(\frac{{\xi}_w^2}{w_\xi^2}
+\frac{{\eta}_w^2}{w_\eta^2}\right)
\right]}
\exp{\left [-i k_0 \left({\bar z} +\frac{\xi_R^2}{2 R_{c\xi}}
+\frac{\eta_R^2}{2 R_{c\eta}}\right )
\right]}.
$$ {#eq:gb}
Note that a general astigmatic Gaussian beam is described in terms of six
parameters: the beam widths $w_{\xi,\eta}$, the phase front curvature radii
$R_{c\xi,\eta}$ and the intensity and phase ellipses rotation angles $φ_{w,R}$.
Simple astigmatic beams can be described in terms of 5 parameters only, because
the phase and intensity ellipses are aligned, i.e., $φ_w=φ_R\equivφ$:
$w_{\xi,\eta}$, $R_{c\xi,\eta}$, $φ$ or alternatively by the beam waists
$w_{0\xi,\eta}$, the waists $\bar z$ coordinates $d_{0\xi,\eta}$, and $φ$,
where $R_{c\xi,\eta}$, $w_{\xi,\eta}$ are related to $d_{0\xi,\eta}$,
$w_{0\xi,\eta}$ by the following equations:
$$
\begin{aligned}
R_{cj} &= [({\bar z}- d_{0j})^2+z_{Rj}^2]/({\bar z}- d_{0j}) \\
w_j &= w_{0j} \sqrt{1+({\bar z}- d_{0j})^2/z_{Rj}^2},
\end{aligned}
$$ {#eq:rciw}
and $z_{Rj}= k_0 w_{0j}^2/2$ is the Raylegh length. According to
[@eq:rciw], a convergent beam (${\bar z} < d_{0j}$) has $R_{cj}<0$, while a
divergent beam has $R_{cj}>0$.
## QO beam tracing equations
The beam tracing equations and the algorithm for their solution are described
in detail in [@gray].
The "extended" rays obey to the following quasi-optical ray-tracing equations
that are coupled together through an additional constraint in the form of a
partial differential equation:
$$
\begin{aligned}
\frac{d {\bf x}}{dσ} &=
+{∂ Λ \over ∂ {\bf N}} \biggr |_{Λ=0} \\
\frac{d {\bf N}}{dσ} &=
-{∂ Λ \over ∂ {\bf x}} \biggr |_{Λ=0} \\
\frac{∂ Λ}{∂ {\bf N}} &\cdot ∇ S_I = 0
\end{aligned}
$$
where the function $Λ ({\bf x},{\bf k},ω)$ is the QO dispersion
relation, which reads
$$
Λ = N² - N_c²({\bf x}, N_\parallel, ω)
- |∇ S_I|² + \frac{1}{2}(\mathbf{b} ⋅ ∇ S_I )^2
\frac{∂² N_s²}{∂{N_\parallel}²} = 0
$$ {#eq:eqlam}
being $\mathbf{b}=\mathbf{B}/B$, $N_\parallel = {\mathbf N} \cdot \mathbf{b}$,
and $N_c({\bf x}, N_\parallel, ω)$ the solution of the cold dispersion relation
for the considered mode.
In GRAY three choices for the integration variable $σ$ are available, i.e.:
1. the arclength along the trajectory $s$,
2. the time $τ=ct$, and
3. the real part of the eikonal function $S_R$.
The default option is the variable $s$ and the QO ray equations become:
$$
\begin{aligned}
\frac{d{\bf x}}{ds} &=
+\frac{∂ Λ /∂ {\bf N}}
{|∂ Λ /∂ {\bf N}|} \biggr |_{Λ=0} \\
\frac{d{\bf N}}{ds} &=
-\frac{∂ Λ /∂ {\bf x}}
{|∂ Λ /∂ {\bf N}|} \biggr |_{Λ=0} \\
\frac{∂ Λ}{∂ {\bf N}} &\cdot ∇ S_I = 0
\end{aligned}
$$ {#eq:qort}
## Ray initial conditions
The QO ray equations [@eq:qort] are solved for $N_T= N_r \times N_\vartheta
+1$ rays distributed in order to simulate the Gaussian pattern of an actual
antenna, with initial position on a suitable surface at the antenna centered
on the beam axis.
The $N_r$ rays are distributed radially up to a "cut-off" radius $\tilde ρ_{max}$
defined as \label{eq:rhomax} $\tilde ρ_{max}^2=-k_0 S_{I,max}$ such that the beam
carries a fraction of the input power equal to $[1-\exp({-2 \tilde ρ_{max}^2)]}$.
The $N_\vartheta$ angular rays are distributed at constant electric field
amplitude (i.e. at $S_I = \text{const}$). Details are given in [@gray].
Care must be taken in the proper choice of the integration step to avoid the
occurrence of numerical instabilities due to the last equation in the set
[@eq:qort]. The value must be tuned with respect to the number of rays (i.e.,
to the distance between rays).
The code can be run also as a "standard" ray-tracing code, simply imposing
$S_I = 0$ in [@eq:eqlam;@eq:qort]. In this case the initial conditions
are given to asymptotically match, for $\vert {\bar z}- d_{0j} \vert \gg
z_{Rj}$, the ray distribution used for the QO ray-tracing.
## Launching coordinates and wave vector
The launching coordinates of the central ray of the EC beam will be denoted
either as $(x_0, y_0, z_0)$, or $(R_0, φ_0, Z_0)$, depending on the
coordinate system used (cartesian or cylindrical)
$$
\begin{aligned}
x_0 &= R_0\cosφ_0 \\
y_0 &= R_0\sinφ_0 \\
z_0 &= Z_0.
\end{aligned}
$$
and the launched wavevector $\bf N$ will have components $(N_{x0}, N_{y0},
N_{z0})$, and $(N_{R0}, N_{φ 0}, N_{Z0})$, related by
$$
\begin{aligned}
N_{x0} &= N_{R0} \cosφ_0 - N_{φ 0} \sinφ_0, \\
N_{y0} &= N_{R0} \sinφ_0 + N_{φ 0} \cosφ_0, \\
N_{z0} &= N_{Z0}
\end{aligned}
$$
## EC Launching angles ($α,β$)
The poloidal and toroidal angles $α, β$ are defined in terms of the
cylindrical components of the wavevector
$$
\begin{aligned}
N_{R0} &= -\cosβ \cosα, \\
N_{φ0} &= +\sinβ, \\
N_{Z0} &= -\cosβ \sinα
\end{aligned}
$$ {#eq:ncyl}
with $-180° ≤ α ≤ 180°$, and $-90° ≤ β ≤ 90°$, so that
$$
\begin{aligned}
\tanα &= N_{Z0}/N_{R0}, \\
\sinβ &= N_{φ 0}
\end{aligned}
$$ {#eq:albt}
A 1-D scan of launch angle with constant toroidal component at launch
($N_{φ 0}$) is achieved by varying only $α$, keeping $β$ fixed.
Injection at $β=0, α=0$ results in a ray launched horizontally and in
a poloidal plane towards the machine centre.
The above choice is quite convenient to perform physics simulations, since EC
results are invariant under toroidal rotation, due to axisymmetry.
This convention is the same used for the EC injection angles in ITER
[@angles].
## ECRH and absorption models
The EC power $P$ is assumed to evolve along the ray trajectory obeying to the
following equation
$$
\frac{dP}{ds} = -α P,
$$ {#eq:pincta}
where here $α$ is the absorption coefficient
$$
α = 2 \frac{ω}{c} \frac {{\text{Im}}(Λ_w)}
{|∂ Λ /∂ {\bf{N}}|} \biggr|_{Λ=0}
≈ 4 \frac{ω}{c} {{\text {Im}}(N_{\perp w})}
\frac {N_{\perp}} {|{∂ Λ}/{∂ {\bf N}|}} \biggr|_{Λ=0}
= 2{{\text{Im}}(k_{\perp w})} \frac{v_{g\perp}} v_{g}.
$$ {eq:alpha}
being $N_{\perp w}$ (and $k_{\perp w}$) the perpendicular refractive index (and
wave vector) solution of the relativistic dispersion relation for EC waves
$$
Λ_w = N^2-N_{\parallel}^2-N_{\perp w}^2=0
$$
The warm dispersion relation $Λ_w$ is solved up to the desired Larmor
radius order either in the weakly or the fully relativistic approximation as
described in [@dispersion].
Integration of [@eq:pincta] yields the local transmitted and deposited
power in terms of the optical depth $τ= \int_0^{s}{α(s') d s'}$ as
$$
P(s)=P_0 e^{-τ(s)},
\quad \mathrm{and} \quad
P_{abs} (s)=P_0 [1-e^{-τ}] ,
$$
respectively, being $P_0$ the injected power.
The flux surface averaged absorbed power density $p(ρ)=dP_{abs}/dV$ is
computed as the the ratio between the power deposited within the volume $dV$
between two adjacent flux surfaces and the volume itself. At each position
along the ray trajectory (parametrized by $s$), the absorbed power density can
be written in terms of the absorption coefficient as
$$
p = P₀ α(s) e^{-τ(s)} \frac{δs}{δV}
$$ {#eq:pav}
$δs$ being the ray length between two adjacent magnetic surfaces, and $δV$ the
associated volume.
## EC Current Drive
Within the framework of the linear adjoint formulation, the flux surface
averaged EC driven current density is given by
$$
\langle J_{\parallel}\rangle = {\mathcal R}^* \, p
$$ {#eq:jav}
where
${\mathcal R}^*$ is a current drive efficiency, which can be expressed as a ratio
between two integrals in momentum space
$$
{\mathcal R}^*= \frac{e}{m c \nu_c} \frac{\langle B \rangle}{B_m}
\frac{\int{d{\bf u} {\mathcal P}({\bf u}) \,
\eta_{\bf u}({\bf u})}}{\int{d{\bf u} {\mathcal P}({\bf u}) }}
$$ {#eq:effr}
where $\nu_c=4 \pi n e^4 Λ_c/(m^2 c^3)$ is the collision frequency, with
$Λ_c$ the Coulomb logarithm, and $B_m$, $\langle B \rangle$ are the
minimum value and the flux surface averaged value of the magnetic field on the
given magnetic surface, respectively.
The functions ${\mathcal P}({\bf u})$ and $\eta_{\bf u}({\bf u})$ are the
normalized absorbed power density and current drive efficiency per unit
momentum ${\bf u}={\bf p}/mc$ [@gray].
Note that the warm wave polarisation is used to compute ${\mathcal P}({\bf u})$.
In the adjoint formulation adopted here, the function $\eta_{\bf u}({\bf u})$
is written in terms of the response function for the current, and its explicit
expression is related to the chosen ECCD model.
The flux surface average driven current density [@eq:jav] can be written as
[@gray]
$$
\langle J_{\parallel}\rangle =
P_0 α(s) e^{-τ(s)} {\mathcal R}^*(s) \frac{δs}{δV}
$$ {#eq:jrtav}
and the equation for the current evolution $I_{cd}$ along the ray trajectory as
$$
\frac{dI_{cd}}{ds} =
-{\mathcal R}^*(s)\frac{1}{2 \pi R_J } \frac{dP}{ds},
$$
where $R_J(\psi)$ is an effective radius for the computation of the driven
current
$$
\frac{1}{R_J}
= \langle \frac{1}{R^2} \rangle \frac{f(\psi)}{ \langle B\rangle}
= \frac{ \langle {B_φ}/{R} \rangle}{ \langle B\rangle}
$$
being $f(\psi) =B_φ R$ the poloidal flux function.
## ECCD Models
Two models for $\eta_{\bf u}({\bf u})$ efficiency in [@eq:effr] are implemented
for ECCD calculations, a Cohen-like module in the high-velocity limit and the
momentum conserving model developed by Marushenko.
The used Cohen-like module, developed explicitly for GRAY, is described in
[@gray]. The Marushchenko module [@marushchenko] has been incorporated into
GRAY as far as the energy part is concerned, while the pitch-angle part on
trapping is based on a local development.
### Current density definitions
In GRAY, three outputs for the EC driven current density are given.
The EC flux surface averaged driven *parallel* current density $\langle
J_{\parallel}\rangle$, that is the output of the ECCD theory, defined as
$$
\langle J_{\parallel}\rangle
= \left \langle\frac{{\bf J}_{cd} \cdot {\bf B}}{B} \right \rangle
= \frac{\langle {{\bf J}_{cd} \cdot {\bf B}}\rangle}
{{\langle B^2 \rangle/}{\langle B \rangle}}.
$$
a *toroidal* driven current density $J_φ$ defined as
\begin{equation}
J_φ =\frac{δ I_{cd}} {δ A}
\label{eq:jphia}
\end{equation}
being $δ I_{cd}$ the current driven within the volume $δ V$ between
two adjacent flux surfaces, and $δ A$ the poloidal area between the two
adjacent flux surfaces, such that the total driven current is computed as
$I_{cd}= \int J_φ dA$.
Finally, an EC flux surface averaged driven current density $J_{cd}$ to be
compared with transport code outputs
$$
J_{cd} = \frac{\langle {\bf J} \cdot {\bf B} \rangle} {B_{ref}}
$$ {#eq:jcd}
with the $B_{ref}$ value dependent on the transport code, i.e, $B_{ref}=B_0$
for ASTRA and CRONOS, and $B_{ref}={\langle B \rangle}$ for JINTRAC.
The above definitions are related to each other in terms of flux surface
averaged quantities, dependent on the equilibrium, i.e.,
$$
\begin{aligned}
J_φ &= \frac{f(\psi)}{\langle B \rangle}
\frac{\langle {1/R^2} \rangle}{\langle{1/R} \rangle}
{\langle J_\parallel \rangle } ,\quad
J_{cd} &= \frac{\langle B^2 \rangle }{\langle B\rangle B_{ref}}
\langle J_\parallel \rangle ,\quad
J_φ &= \frac{B_{ref} f(\psi)}{\langle B^2 \rangle}
\frac{\langle {1/R^2} \rangle}{\langle{1/R} \rangle} J_{cd}.
\end{aligned}
$$ {#eq:ratj}
## ECRH & CD location and profile characterization
Driven current and absorbed power density profiles, $J_{cd}(ρ)$, $p(ρ)$,
can be characterized in term of suitable quantities. In GRAY, two approaches
are followed, both available at each computation, that yields the same results
in case of almost Gaussian profiles. Here, the flux label $ρ$ denotes the
normalized toroidal radius defined as the square root of the toroidal flux
normalized to its edge value.
In the first case, the profiles are characterized in terms of three quantities:
the peak value of the toroidal current density $J_φ$, the radius $ρ$
corresponding to the peak, and the full profile width at 1/e of the peak value.
In addition, the ratio between $J_{cd}/ J_φ$ is computed at the peak radius
via [@eq:ratj] for the two $B_{ref}$ choices.
The second approach applies also to non monotonic profiles. Two average
quantities are computed for both power and current density profiles, namely,
the average radius $\langle ρ \rangle_a$ $(a=p,j)$
$$
\langle ρ \rangle_p = \frac{\int dV ρ p(ρ)}{\int dV p(ρ)} , \qquad
\langle ρ \rangle_j = \frac{\int dA ρ | J_{φ}(ρ)|} {\int dA |J_{φ}(ρ)|}
$$ {#eq:rav}
and average profile width ${δρ}_a$ defined in terms of the variance as
$$
δ ρ_a = 2 \sqrt{2} \langle δ ρ \rangle_a
\qquad \mathrm {with } \qquad
\langle δ ρ \rangle_a^2 = \langle ρ^2 \rangle_a-(\langle ρ \rangle_a)^2
$$ {#eq:drav}
Factor $\sqrt{8}$ is introduced to match with the definition of the full
profile width in case of Gaussian profiles.
Consistently with the above average definitions, we introduce suitable peak
values $p_{0}$ and $J_{φ 0}$, corresponding to those of a Gaussian profile
characterized by [@eq:rav;@eq:drav] and same total absorbed power $P_{abs}$ and
driven current $I_{cd}$
$$
p_0 = \frac{2}{\sqrt{\pi}} \frac{P_{abs}}{{ δ ρ}_p
\left ({dV}/{d ρ}\right)_{\langle ρ \rangle_p}},
\qquad
J_{φ0} = \frac{2}{\sqrt{\pi}} \frac{I_{cd}}{{ δ ρ}_j
\left ({dA}/{d ρ}\right)_{\langle ρ \rangle_j}}.
$$ {#eq:pjgauss}
## Reflection at inner wall and polarisation
A model for wave reflection on a smooth surface is included in GRAY. This is
used to describe beam reflection on the inner wall of the tokamak in the cases
where only partial absorption occurs at the first pass in the plasma. An ideal
conductor is assumed for the reflecting surface, so that the full power of the
incident beam is transferred to the reflected one. The vector refractive index
${\bf N}_{\rm{refl}}$ and the unit electric field $\hat {\bf e}_{\rm{refl}}$ of
the reflected wave are
\begin{equation}
{\bf N}_{\rm{refl}} =
{\bf N}_{\rm{in}} - 2 ({\bf N}_{\rm{in}}
\cdot \hat {\bf n}) \hat {\bf n}, \qquad
\hat {\bf e}_{\rm{refl}} =
-\hat {\bf e}_{\rm{in}}
+ 2 (\hat {\bf e}_{\rm{in}} \cdot \hat {\bf n}) \hat {\bf n},
\end{equation}
being ${\bf N}_{\rm{in}}$ and $\hat {\bf e}_{\rm{in}}$ the vector refractive
index and the unit electric field of the incoming wave, and $\hat {\bf n}$ the
normal unit vector to the wall at the beam incidence point.
The Stokes parameter for the unit electric vector $\hat {\bf e}$ in vacuum are
defined in the beam reference system $({\bar x},{\bar y},{\bar z})$ as
$$
\begin{aligned}
I &= \vert \hat e_{\bar x} \vert^2 + \vert \hat e_{\bar y} \vert^2 = 1 \\
Q &= \vert \hat e_{\bar x} \vert^2 - \vert \hat e_{\bar y} \vert^2 \\
U &= 2 \cdot {\rm Re} (\hat e_{\bar x} \hat e_{\bar y}^*) \\
V &= 2 \cdot {\rm Im} (\hat e_{\bar x} \hat e_{\bar y}^*).
\end{aligned}
$$ {#eq:stokes}
Alternatively, the two angles $\psi_p$ and $\chi_p$ can be used:
$$
\begin{aligned}
Q &= \cos {2 \psi_p} \cos {2 \chi_p} \\
U &= \sin {2 \psi_p} \cos {2 \chi_p} \\
V &= \sin {2 \chi_p}
\end{aligned}
$$
which define respectively the major axis orientation and the ellipticity of the
polarisation ellipse. The polarisation parameters of the reflected wave are
used to compute the coupling with the Ordinary (OM) and Extraordinary (XM)
modes at the vacuum-plasma interface before the calculation of the second pass
in the plasma. At the second pass both modes are traced, taking into account
that the power fraction coupled to each mode is
$$
P_{\rm O,X} =
\frac{P_{\rm in}}{2}
(1 + Q_{\rm in} Q_{\rm O,X}
+ U_{\rm in} U_{\rm O,X}
+ V_{\rm in} V_{\rm O,X}).
$$
Note that the polarisation vectors of OM and XM form an orthogonal base:
$\psi_{p{\rm O}}=\psi_{p{\rm X}}+\pi/2$, $\chi_{p{\rm O}}=-\chi_{p{\rm X}}$ and
as a consequence $Q_{\rm O}=-Q_{\rm X}$, $U_{\rm O}=-U_{\rm X}$, and $V_{\rm
O}=-V_{\rm X}$, so that $P_{\rm O} + P_{\rm X} = P_{\rm in}$, i.e. all the
incoming power is coupled to the plasma.

566
doc/3.io-files.md Normal file
View File

@ -0,0 +1,566 @@
# Input and output files {#sec:io-files}
This section describes the input data required by GRAY and the output
files that are saved and stored for the GRT-161 analysis. In [@tbl:io]
the assigned unit numbers used for various input and output files in GRAY are
listed. Shell scripts allow to run the code for various input data that are
varied by means of suitable loops.
---------------------------------------------------------------------------------------------------------------------------
Unit Number I/O Content Filename
------------- -------- ---------------------------------------------- -----------------------------------------------------
2 I Input data `gray_params.data`
99 I Equilibrium file EQDSK `filenmeqq.eqdsk`
98 I Kinetic profiles `filenmeprf.prf`
97 I Beam data `filenmebm.txt`
4 O Data for central ray None
7 O Global data and results None / assigned by shell script
48 O ECRH&CD profiles None / assigned by shell script
33 O Data for outmost rays None
8 O Beam cross section shape None
9 O Rays distribution at the end None
of the integration path
12 O Beam transverse sizes None
17 O Beam tracing error on Hamiltonian None
55 O Kinetic profiles None
56 O Flux averaged quantities None
70 O EC resonance surface at relevant harmonics None
71 O Flux surface contours at None
$\sqrt{\psi}=\text{const}$
78 O Record of input parameters `headers.txt` / attached to output by shell script
---------------------------------------------------------------------------------------------------------------------------
Table: GRAY I/O Unit Numbers {#tbl:io}
## Input Files {#sec:input-files}
To run GRAY, the user must supply a `gray_params.data` file and two
files, containing information about the MHD equilibrium and the kinetic
profiles, respectively.
The variables and quantities in `gray_params.data` are listed in
[@tbl:input1;@tbl:input2;@tbl:input3], suitably grouped together.
The equilibrium information is provided via a G-EQDSK file (with extension
`.eqdsk`), with conventions specified as in [@cocos].
The kinetic profiles are provided in an ASCII file (with extension `.prf`).
The format of the G-EQDSK file is described in [@sec:eqdisk], while the format
of the `.prf` file for the profiles is the following quantities defined in
[@tbl:profiles1]:
```fortran
read (98,*) npp
do i=1,npp
read(98,*) psin(i),Te(i),ne(i),Zeff(i)
end do
```
The beam parameters are read either from the `gray_params.data` file, or
from an ASCII file (with extension `.txt`), depending on the value of the
`ibeam` parameter as specified in [@tbl:input1]. If the ASCII file
is used, the user can supply multiple launching conditions, and/or use a
general astigmatic Gaussian beam. The format of the `.txt` file is the
following, for `ibeam`=1 and `ibeam`=2 respectively (quantities defined
in [@tbl:profiles2]):
```fortran
! +++ IBEAM=1 +++
read(97,*) nsteer
do i=1,nsteer
read(97,*) gamma(i),alpha0(i),beta0(i),x0mm(i),y0mm(i),z0mm(i), &
w0xi(i),d0eta(i),w0xi(i),d0eta(i),phiw(i)
end do
! +++ IBEAM=2 +++
read(97,*) nsteer
do i=1,nisteer
read(97,*) gamma(i),alpha0(i),beta0(i),x0mm(i),y0mm(i),z0mm(i), &
wxi(i),weta(i),rcixi(i),rcieta(i),phiw(i),phir(i)
end do
```
## G-EQDSK format {#sec:eqdisk}
The G EQDSK file provides information on:
1. pressure,
2. poloidal current function,
3. $q$ profile,
4. plasma boundary,
5. limiter contour
All quantities are defined on a uniform flux grid from the magnetic axis to the
plasma boundary and the poloidal flux function on the rectangular computation
grid. A right-handed cylindrical coordinate system $(R, φ, Ζ)$ is used.
### Variables
In order of appearance in the file:
-------- --------- -------------------------------------
Name Type Description
--------- --------- -------------------------------------
`case` String(6) Identification string
`nw` Integer Number of horizontal $R$ grid points
`nh` Integer Number of vertical $Z$ grid points
---------------------------------------------------------
Table: **Miscellanea** {#tbl:eqdisk-misc}
--------- --------- --------------- -----------------------------------------------
Name Type Unit Description
--------- --------- --------------- -----------------------------------------------
`rdim` Real m Horizontal dimension of the computational box
`zdim` Real m Vertical dimension of the computational box
`rleft` Real m Minimum R of the rectangular computational box
`zmid` Real m Z of center of the computational box
`rmaxis` Real m R of the magnetic axis
`zmaxis` Real m $Z$ of the magnetic axis
-----------------------------------------------------------------------------
Table: **Geometry** {#tbl:eqdisk-geom}
--------- --------- --------------- -------------------------------------------------------
Name Type Unit Description
--------- --------- --------------- -------------------------------------------------------
`simag` Real Wb/rad Poloidal flux at the magnetic axis
`sibry` Real Wb/rad Poloidal flux at the plasma boundary
`rcentr` Real m $R$ of vacuum toroidal magnetic field `bcentr`
`bcentr` Real T Vacuum toroidal magnetic field at `rcentr`
`current` Real A Plasma current
`fpol` Real mT Poloidal current function, $F = RB_T$ on the flux grid
`pres` Real Pa Plasma pressure on a uniform flux grid
`ffprim` Real (mT²)/(Wb/rad) $FF'(ψ)$ on a uniform flux grid
`pprime` Real Pa/(Wb/rad) $P'(ψ)$ on a uniform flux grid
`psizr` Real Wb/rad Poloidal flux on the rectangular grid points
`qpsi` Real 1 $q$ values on uniform flux grid from axis to boundary
-------------------------------------------------------------------------------------------
Table: **Magnetic equilibrium** {#tbl:eqdisk-eq}
--------- --------- --------------- -------------------------------------------------------
Name Type Unit Description
--------- --------- --------------- -------------------------------------------------------
`nbbbs` Integer 1 Number of boundary points
`limitr` Integer 1 Number of limiter points
`rbbbs` Real m $R$ of boundary points
`zbbbs` Real m $Z$ of boundary points
`rlim` Real m $R$ of surrounding limiter contour
`zlim` Real m $Z$ of surrounding limiter contour
--------------------------------------------------------------
Table: **Plasma boundary** {#tbl:eqdisk-bound}
### Toroidal Current Density
The toroidal current $J_T$ (A/m²) is related to $P'(ψ)$ and $FF'(ψ)$ through
$$
J_T = R P'(ψ) + FF'(ψ) / R
$$
### Example Fortran 77 code
The following snippet can be used to load a G-EQDSK file:
```fortran
character*10 case(6)
dimension psirz(nw,nh),fpol(1),pres(1),ffprim(1),
. pprime(1),qpsi(1),rbbbs(1),zbbbs(1),
. rlim(1),zlim(1)
c
read (neqdsk,2000) (case(i),i=1,6),idum,nw,nh
read (neqdsk,2020) rdim,zdim,rcentr,rleft,zmid
read (neqdsk,2020) rmaxis,zmaxis,simag,sibry,bcentr
read (neqdsk,2020) current,simag,xdum,rmaxis,xdum
read (neqdsk,2020) zmaxis,xdum,sibry,xdum,xdum
read (neqdsk,2020) (fpol(i),i=1,nw)
read (neqdsk,2020) (pres(i),i=1,nw)
read (neqdsk,2020) (ffprim(i),i=1,nw)
read (neqdsk,2020) (pprime(i),i=1,nw)
read (neqdsk,2020) ((psirz(i,j),i=1,nw),j=1,nh)
read (neqdsk,2020) (qpsi(i),i=1,nw)
read (neqdsk,2022) nbbbs,limitr
read (neqdsk,2020) (rbbbs(i),zbbbs(i),i=1,nbbbs)
read (neqdsk,2020) (rlim(i),zlim(i),i=1,limitr)
c
2000 format (6a8,3i4)
2020 format (5e16.9)
2022 format (2i5)
```
## Output Files
GRAY outputs are given in ASCII files at each GRAY execution.
[@tbl:output7;@tbl:output48] describe the outputs reported in units 7 and 48,
respectively.
----------------------------------------------------------------------------------------------------------------------------
Variable Type Units Valid range Definition
---------------- ----------- --------- ----------------------- ------------------------------------------------------------
`alpha0` Real deg $-180 < x ≤ 180$ Poloidal injection angle $α$, defined in [@eq:albt].
`beta0` Real deg $-90 < x ≤ 90$ Toroidal injection angle $β$, defined in [@eq:albt].
`fghz` Real GHz $x>0$ EC frequency.
`P0` Real MW $x>0$ EC injected power.
`Nrayr` Integer 1 $1 ≤ n ≤ 31$ Number of rays $N_r$ in radial direction + 1 in
the center, ${\tt Nrayr} = N_r +1$.
`Nrayth` Integer 1 $1 ≤ n ≤ 36$ Number of rays $N_{\theta}$ in angular direction.
`rwmax` Real $x > 0$ "cut-off" size $\tilde ρ_{max}$ of the gaussian beam.
(typical $1 ≤ {\tt rwmax} ≤ 1.5$), defined at page.
`x0` Real cm $X$ coordinate of the launching point.
`y0` Real cm $Y$ coordinate of the launching point.
`z0` Real cm $Z$ coordinate of the launching point.
`w0xi` Real cm $x > 0$ Beam waist $w_{0,\xi}$ in beam reference system.
along $\xi$, defined in [@eq:rciw].
`w0eta` Real cm $x > 0$ Beam waist $w_{0,\eta}$ in beam reference system.
along $\eta$, defined in [@eq:rciw].
`d0xi` Real cm $\bar{z}$ coordinate of beam waist $w_{0,\xi}$,.
defined in [@eq:rciw].
`d0eta` Real cm $\bar{z}$ coordinate of beam waist $w_{0,\eta}$,.
defined in [@eq:rciw].
`phiw` Real deg $-90 < x ≤ 90$ Rotation angle $φ_w=φ_R$ of local beam coordinate.
system, defined in [@eq:phiwr].
`ibeam` Integer 0, 1, 2 Input source for beam data:.
0=simple astigmatic beam with parameters as above,.
1=simple astigmatic beam from `filenmbm`,.
2=general astigmatic beam from `filenmbm`.
`filenmbm` String len$(s)≤ 24$ Name of file (extension `.txt` appended) with beam.
parameters, used if ${\tt ibeam} >0$.
`iox` Integer 1, 2 1=Ordinary mode (OM), 2=Extraordinary (XM) mode.
`psipol0` Real deg $-90 < x ≤ 90$ Wave polarisation angle $\psi_p$ at the launching point.
`chipol0` Real deg $-45 ≤ x ≤ 45$ Wave polarisation angle $\chi_p$ at the launching point.
----------------------------------------------------------------------------------------------------------------------------
Table: GRAY input data `gray_params.data` - EC wave {#tbl:input1}
----------------------------------------------------------------------------------------------------------------------------
Variable Type Units Valid range Definition
---------------- ----------- --------- ----------------------- ------------------------------------------------------------
`iequil` Integer 0, 1, 2 Magnetic equilibrium model:
0=vacuum (no plasma at all),
1=analytical
2=G-EQDSK.
`ixp` Integer -1, 0, 1 X point occurrence:
-1=bottom,
0=none,
+1=top.
`iprof` Integer 0, 1 Kinetic profiles:
0=analytical
1=numerical.
`filenmeqq` String len$(s)≤ 24$ Name of EQDSK file (extension `.eqdsk` appended).
`ipsinorm` Integer 0, 1 0=dimensional (default),
1=normalized (obsolete, for some old files
psi$(R,z)$ in `filenmeqq`.
`sspl` Real 1 $x > 0$ Tension of spline fit for psi (${\tt sspl} \ll 1$ typical),
0=interpolation.
`factb` Real 1 $x > 0$ Numerical factor to rescale the magnetic field
$B \rightarrow B \cdot {\tt factb}$.
`factt` Real 1 $x > 0$ Numerical factor to rescale the electron temperature
$T_e \rightarrow T_e \cdot {\tt factt}
\cdot {\tt factb}^{\tt ab}$.
`factn` Real 1 $x > 0$ Numerical factor to rescale the electron density
$n_e \rightarrow n_e \cdot {\tt factn}
\cdot {\tt factb}^{\tt ab}$.
`iscal` Int 1, 2 Model for $n_e$, $T_e$ scaling with $B$:
1=constant $n_{Greenwald}$ (`ab`=1),
2=none (`ab`=0).
`filenmprf` String len$(s) ≤ 24$ Name of file for kinetic profiles
(extension `.prf` appended).
`psdbnd` Real 1 $x > 0$ Normalized psi value at the plasma boundary where
$n_e$ is set to zero (typ. $1 ≤ {\tt psdbnd} ≤ 1.1$).
`sgnbphi` Real 1 -1, +1 Signum of toroidal B, used if `icocos`=0.
`sgniphi` Real 1 -1, +1 Signum of toroidal plasma current $I$, used if `icocos`=0.
`icocos` Int 0-8, 10-18 COCOS index used in `filenmeqq` as defined in [@cocos]:
0=no COCOS convention and psi in Wb/rad,
10=means no convention and psi in Wb.
----------------------------------------------------------------------------------------------------------------------------
Table: GRAY input data `gray_params.data` - plasma data {#tbl:input2}
----------------------------------------------------------------------------------------------------------------------------
Variable Type Units Valid range Definition
---------------- ----------- --------- ----------------------- ------------------------------------------------------------
`iwarm` Integer 0, 1, 2, 3 Absorption model:
0=none (α=0),
1=weakly relativistic,
2=fully relativistic (fast),
3=fully relativistic (slow).
`ilarm` Integer 1 $n ≥ 1$ Order of Larmor radius expansion for absorption
computation ${\tt ilarm}>$ local EC harmonic number.
`ieccd` Integer 0, 1, 11 Current drive model:
0=none,
1=Cohen,
11=Marushchenko.
`igrad` Integer 0, 1 Ray-tracing model:
0=optical,
1=quasi-optical (requires ${\tt nrayr} \ge 5$).
`idst` Integer 0, 1, 2 Ray-tracing integration variable:
0=$s$,
e1=$c \cdot t$,
2=$S_R$,
(default=0).
`dst` Real cm $x > 0$ Spatial integration step.
`nstep` Integer 1 $0 ≤ n ≤ 8000$ Maximum number of integration steps.
`istprj` Integer 1 $1 ≤ n ≤ {\tt nstep}$ Subsampling factor for beam cross section
data output (units 8, 12).
`istpl` Integer 1 $1 ≤ n ≤ {\tt nstep}$ Subsampling factor for outmost rays
data output (unit 33).
`ipec` Integer 0, 1 Grid spacing for ECRH&CD profiles:
0=equispaced in $\psi$ (obsolete),
1=equispaced in $\sqrt{\psi}$.
`nnd` Integer 1 $2 ≤ n ≤ 5001$ Number of points in the ECRH&CD profile grid.
`ipass` Integer $-2,1, 2$ $\vert{\tt ipass}\vert$=number of passes into plasma:
-2=reflection at `rwallm`,
+2=reflection at limiter.
Surface given in EQDSK.
`rwallm` Real m $x > 0$ Inner wall radius for 2nd pass calculations,
used only for `ipass`=$-2$.
----------------------------------------------------------------------------------------------------------------------------
Table: GRAY input data `gray_params.data` - ECRH&CD models and code parameters {#tbl:input3}
----------------------------------------------------------------------------------------------------------------------------
Variable Type Units Valid range Definition
---------------- ----------- --------- ----------------------- ------------------------------------------------------------
`npp` Integer 1 $2 ≤ n ≤ 250$ Number of points in `psin` table
`psin` real 1 $0 ≤ x ≤$ `psdbnd` Poloidal flux $\psi$ normalized over the value at the LCS
`Te` real keV $x ≥ 0$ Electron temperature
`ne` real 10¹⁹m⁻³ $x ≥ 0$ Electron density
`Zeff` real 1 $x ≥ 0$ Effective charge, $Z_{\rm eff}$
----------------------------------------------------------------------------------------------------------------------------
Table: GRAY input data `filenmprf.prf` - plasma profiles {#tbl:profiles1}
----------------------------------------------------------------------------------------------------------------------------
Variable Type Units Valid range Definition
---------------- ----------- --------- ----------------------- ------------------------------------------------------------
`nsteer` Integer 1 $n ≤ 50$ Number launching conditions in table.
`gamma` Real deg Steering angle w.r.t. a reference position (unused).
`alpha0` Real deg $-180 < x ≤ 180$ Poloidal injection angle $α$.
`beta0` Real deg $-90 ≤ x ≤ 90$ Toroidal injection angle $β$.
`x0mm` Real mm $X$ coordinate of the launching point.
`y0mm` Real mm $Y$ coordinate of the launching point.
`z0mm` Real mm $Z$ coordinate of the launching point.
`w0xi` Real mm $x > 0$ Beam waist $w_{0,\xi}$ along $\xi$.
`w0eta` Real mm $x > 0$ Beam waist $w_{0,\eta}$ along $\eta$.
`d0xi` Real mm $\bar z$ coordinate of beam waist $w_{0,\xi}$,
$\bar z=0$ at launching point.
`d0eta` Real mm $\bar z$ coordinate of beam waist $w_{0,\eta}$,
$\bar z=0$ at launching point.
`wxi` Real mm $x > 0$ Beam width $w_{\xi}$ at the launching point.
`weta` Real mm $x > 0$ Beam width $w_{\eta}$ at the launching point.
`rcixi` Real mm⁻¹ Inverse of phase front curvature radius $1/R_{\xi}$
at the launching point.
`rcieta` Real mm⁻¹ Inverse of phase front curvature radius $1/R_{\eta}$
at the launching point.
`phiw` Real deg Rotation angle $φ_w$ of the $(\xi_w,\eta_w)$ reference
system, defined in [@eq:phiwr].
`phir` Real deg Rotation angle $φ_R$ of the $(\xi_R,\eta_R)$ reference
system, defined in [@eq:phiwr].
----------------------------------------------------------------------------------------------------------------------------
Table: GRAY input data `filenmbm.prf` - launched beam parameters {#tbl:profiles2}
---------------------------------------------------------------------------------------------------
Variable Type Units Definition
---------------- ----------- --------- ------------------------------------------------------------
`Icd` Real kA EC total driven current $I_{cd}$.
`Pa` Real MW EC total absorbed power $P_{abs}$.
`Jphimx` Real MA⋅m⁻² EC peak current density $J_{φ}= dI_{cd}/dA$.
`dPdVmx` Real MW⋅m⁻³ EC peak power density $dP/dV$.
`rhotj` Real 1 $ρ$ value corresponding to `Jphimx`.
`rhotp` Real 1 $ρ$ value corresponding to `dPdVmx`.
`drhotj` Real 1 Full width at $1/e$ of driven current density profile.
`drhotp` Real 1 Full width at $1/e$ of power density profile.
`Jphip` Real MA⋅m⁻² EC peak current density $J_{φ 0}$ from Gaussian profile,
defined in [@eq:pjgauss].
`dPdVp` Real MW⋅m⁻³ EC peak power density $p_0$ from Gaussian profile,
defined in [@eq:pjgauss].
`rhotjava` Real 1 $ρ$ value averaged over current density profile,
defined in [@eq:rav].
`rhotpav` Real 1 $ρ$ value averaged over power density profile,
defined in [@eq:rav].
`drhotjava` Real 1 Full width of the driven current density profile,
defined in [@eq:drav].
`drhotpav` Real 1 Full width of the driven power density profile,
defined in [@eq:drav].
`ratjbmx` Real 1 Ratio $J_{cd}/J_{φ}$ at $ρ=$`rhotjava`,
with $J_{cd}=\langle \bold{J}\cdot \bold{B} \rangle
/\langle \mathbf{B} \rangle$.
`ratjamx` Real 1 Ratio $J_{cd}/J_{φ}$ at $ρ=$`rhotjava`,
with $J_{cd}=\langle \bold{J}\cdot \bold{B} \rangle/B_0$
`stmx` Real cm Path from the launching point and peak $dP/dV$
for the central ray.
`psipol` Real ?? $\psi$ polarisation angle at vacuum-plasma boundary.
`chipol` Real ?? $\chi$ polarisation angle at vacuum-plasma boundary.
`index_rt` Integer Index encoding mode and pass number, see [@sec:index_rt].
---------------------------------------------------------------------------------------------------
Table: GRAY output data - unit 7 {#tbl:output7}
---------------------------------------------------------------------------------------------------
Variable Type Units Definition
---------------- ----------- --------- ------------------------------------------------------------
`psin ` Real 1 Normalized poloidal flux.
`rhot` Real 1 Normalized minor radius $ρ$.
`Jphi` Real MA⋅m⁻² EC current density $J_{φ}= dI_{cd}/dA$,
with $A$ the area of the poloidal section labelled by $ρ$.
`Jcdb` Real MA⋅m⁻² EC current density
$J_{cd}=\langle \bold{J}\cdot\bold{B} \rangle
/\langle \mathbf{B} \rangle$.
`dPdV` Real MW⋅m⁻³ EC power density $p(ρ)=dP/dV$.
`Icdins` Real kA EC current driven inside surface of radius $ρ$,
$I_{ins}(ρ)=\int_0^{ρ} J_{cd} dA$.
`Pins` Real MW EC power absorbed inside surface of radius $ρ$,
$P_{ins}(ρ)=\int_0^{ρ}p dV$.
`P%` Real 1 Fraction of power deposited inside radius $ρ$,
`P%`$(ρ)=P_{ins}/P_{abs}$.
`index_rt` Integer Index encoding mode and pass number, see [@sec:index_rt].
---------------------------------------------------------------------------------------------------
Table: GRAY output data - unit 48 {#tbl:output48}

24
doc/4.implementation.md Normal file
View File

@ -0,0 +1,24 @@
# Implementation
## `index_rt` {#sec:index_rt}
The `index_rt` is a unique index assigned to each combination of beam
propagation mode and number of passes into the plasma.
Initially `index_rt` is 1 for the ordinary mode or 2 for the extraordinary
mode. Due to the mode mixing, on subsequent passes each beam splits into two
modes and the `index_rt` is updated as:
```fortran
index_rt = 2*index_rt + 1 ! for the O mode
index_rt = 2*index_rt + 2 ! for the X mode
```
It follows that ordinary(extraordinary) modes respectively have odd(even)
indices and the number of passes is given by $\lfloor \log₂(1 + \tt index\_rt)
\rfloor$. For example, an `index_rt`=19 denotes the following chain:
$$
\begin{aligned}
\text{mode:} && O &→ X → O → O \\
\text{\tt index\_rt:} && 1 &→ 4 → 9 → 19
\end{aligned}
$$

57
doc/5.changelog.md Normal file
View File

@ -0,0 +1,57 @@
# Changelog
The code GRAY is maintained under Git revision control in a local repository at
ISTP-CNR. The changes in input/output variables and parameters names are listed
in [@tbl:name-changes], below.
---------------------------------------------------------------------------------------------------
Unit Rev. 4 Rev. 19 Rev. 24+ Rev. 60 Notes
------- ----------- ------------ ------------ ------------ ----------------------------------------
2,78 `alfac` `alpha0`
2,78 `betac` `beta0`
2,78 `nray` `nrayr`
2,78 `ktx` `nrayth`
2,78 `rmx` `rwmax`
2,78 `x00` `x0`
2,78 `y00` `y0`
2,78 `z00` `z0`
2,78 `w0xt` `w0xi`
2,78 `w0yt` `w0eta`
2,78 `pw0xt` `d0xi`
2,78 `pw0yt` `d0eta`
2,78 `awr` `phiw`
2,78 `psipola` `psipol0`
2,78 `chipola` `chipol0`
7 `-` `ratjbmx` Column header missing until rev. 24.
7 `-` `ratjamx`
7 `-` `Jphip`
7 `-` `dPdVp`
7 `polpsi` `psipol`
7 `polchi` `chipol`
48 `Jcda ` `Jcdb` `Jcda`: ASTRA, CRONOS,...,
`Jcdb`: JINTRAC def. See [@eq:jcd].
---------------------------------------------------------------------------------------------------
Table: Changes in variables names/definitions {#tbl:name-changes}

43
doc/Makefile Normal file
View File

@ -0,0 +1,43 @@
# Load the configure script variables
-include ../configure.mk
##
## Options
##
# Pandoc flags
FLAGS = --filter pandoc-crossref --citeproc --toc --number-sections
PDF_FLAGS = --pdf-engine=xelatex
HTML_FLAGS = --standalone --katex$(KATEX_URL)
# Rebuild everything if the makefile changed
.EXTRA_PREREQS += Makefile
# User manual
DOCDIR = build/doc
SECTIONS = $(wildcard [0-9].*.md)
MANUALS = $(addprefix $(DOCDIR)/,manual.html manual.pdf res)
##
## Targets
##
.PHONY: all clean
all: $(MANUALS)
clean:
rm -r build
$(DOCDIR)/manual.html: $(SECTIONS) res | $(DOCDIR)
pandoc $(FLAGS) $(HTML_FLAGS) $(filter %.md, $^) -o $@
$(DOCDIR)/res: res | $(DOCDIR)
cp -r $^ $@
$(DOCDIR)/manual.pdf: $(SECTIONS) | $(DOCDIR)
pandoc $(FLAGS) $(PDF_FLAGS) $^ -o $@
# Create directories
$(DOCDIR):
mkdir -p $@

149
doc/res/style.csl Normal file
View File

@ -0,0 +1,149 @@
<?xml version="1.0" encoding="utf-8"?>
<style xmlns="http://purl.org/net/xbiblio/csl" class="in-text" version="1.0" demote-non-dropping-particle="sort-only" default-locale="en-US">
<info>
<title>Elsevier (numeric, with titles)</title>
<id>http://www.zotero.org/styles/elsevier-with-titles</id>
<link href="http://www.zotero.org/styles/elsevier-with-titles" rel="self"/>
<link href="http://www.zotero.org/styles/elsevier-without-titles" rel="template"/>
<link href="http://www.elsevier.com/journals/journal-of-hazardous-materials/0304-3894/guide-for-authors#68001" rel="documentation"/>
<author>
<name>Richard Karnesky</name>
<email>karnesky+zotero@gmail.com</email>
<uri>http://arc.nucapt.northwestern.edu/Richard_Karnesky</uri>
</author>
<contributor>
<name>Rintze Zelle</name>
<uri>http://twitter.com/rintzezelle</uri>
</contributor>
<category citation-format="numeric"/>
<category field="generic-base"/>
<summary>A style for many of Elsevier's journals that includes article titles in the reference list</summary>
<updated>2019-10-15T15:14:08+00:00</updated>
<rights license="http://creativecommons.org/licenses/by-sa/3.0/">This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 License</rights>
</info>
<macro name="author">
<names variable="author">
<name initialize-with="." delimiter=", " delimiter-precedes-last="always"/>
<label form="short" prefix=", "/>
<substitute>
<names variable="editor"/>
<names variable="translator"/>
</substitute>
</names>
</macro>
<macro name="editor">
<names variable="editor">
<name initialize-with="." delimiter=", " delimiter-precedes-last="always"/>
<label form="short" prefix=" (" text-case="capitalize-first" suffix=")"/>
</names>
</macro>
<macro name="year-date">
<choose>
<if variable="issued">
<date variable="issued">
<date-part name="year"/>
</date>
</if>
<else>
<text term="no date" form="short"/>
</else>
</choose>
</macro>
<macro name="publisher">
<text variable="publisher" suffix=", "/>
<text variable="publisher-place" suffix=", "/>
<text macro="year-date"/>
</macro>
<macro name="edition">
<!--TODO: CSL should have low numeric be text (e.g. '3'->'third')-->
<choose>
<if is-numeric="edition">
<group delimiter=" ">
<number variable="edition" form="ordinal"/>
<text term="edition" form="short"/>
</group>
</if>
<else>
<text variable="edition"/>
</else>
</choose>
</macro>
<macro name="access">
<choose>
<if variable="URL">
<text variable="URL"/>
<group prefix=" (" suffix=")" delimiter=" ">
<text term="accessed"/>
<date variable="accessed" form="text"/>
</group>
</if>
</choose>
</macro>
<citation collapse="citation-number">
<sort>
<key variable="citation-number"/>
</sort>
<layout prefix="[" suffix="]" delimiter=",">
<text variable="citation-number"/>
</layout>
</citation>
<bibliography entry-spacing="0" second-field-align="flush">
<layout suffix=".">
<text variable="citation-number" prefix="[" suffix="]"/>
<text macro="author" suffix=", "/>
<choose>
<if type="bill book graphic legal_case legislation motion_picture report song" match="any">
<group delimiter=", ">
<text variable="title"/>
<text macro="edition"/>
<text macro="publisher"/>
</group>
</if>
<else-if type="chapter paper-conference" match="any">
<text variable="title" suffix=", "/>
<text term="in" suffix=": "/>
<text macro="editor" suffix=", "/>
<text variable="container-title" form="short" text-case="title" suffix=", "/>
<text macro="edition" suffix=", "/>
<text macro="publisher"/>
<group delimiter=" ">
<label variable="page" form="short" prefix=": "/>
<text variable="page"/>
</group>
</else-if>
<else-if type="patent">
<group delimiter=", ">
<text variable="title"/>
<text variable="number"/>
<text macro="year-date"/>
</group>
</else-if>
<else-if type="thesis">
<group delimiter=", ">
<text variable="title"/>
<text variable="genre"/>
<text variable="publisher"/>
<text macro="year-date"/>
</group>
</else-if>
<else>
<group delimiter=" ">
<text variable="title" suffix=","/>
<text variable="container-title" form="short" text-case="title" suffix="."/>
<text variable="volume"/>
<text macro="year-date" prefix="(" suffix=")"/>
<text variable="page" form="short"/>
</group>
</else>
</choose>
<choose>
<if variable="DOI">
<text variable="DOI" prefix=". https://doi.org/"/>
</if>
<else>
<text macro="access" prefix=". "/>
</else>
</choose>
</layout>
</bibliography>
</style>

92
doc/res/style.css Normal file
View File

@ -0,0 +1,92 @@
/* Sane box model */
* {
box-sizing: border-box;
}
/* Make headings smaller */
h1 { font-size: 1.8em }
h2 { font-size: 1.4em }
h3 { font-size: 1.1em }
h1, h2, h3 { margin: 1em 0 }
/* Match math and normal mode fonts */
body { font-size: 1.1em }
.katex { font-size: 1.0em !important }
/* Center the title */
header { text-align: center }
/* Inline the authors */
header .author {
display: inline-block;
padding: 0 0.5em;
}
/* Increase caption/table spacing */
div[id^="tbl"] table { margin: 2.5em 0; }
div[id^="tbl"] table caption {
font-weight: bold;
margin-bottom: 1em;
}
/* Increase table row spacing*/
div[id^="tbl"] table td { padding: 0.2em }
/* Proper table header lines */
div[id^="tbl"] table { border-collapse: collapse }
div[id^="tbl"] table th {
border-top: 1px solid #1a1a1a;
border-bottom: 1px solid #1a1a1a;
padding: 0.25em 0.5em 0.25em 0.5em;
}
/* Links color */
a:link, a:visited { color: #1a1a1a }
a:hover { color: #35d7bb }
body {
/* center horizontally */
margin: 0 auto;
padding: 2em;
/* right-shift by the sidebar width */
padding-left: calc(clamp(14em, 30vw, 20em) + 2em);
/* use all remaining width */
width: calc(60vw + clamp(14em, 30vw, 20em) + 2em);
/* override pandoc style */
max-width: initial;
}
/* Navigation sidebar */
nav {
z-index: 1;
position: fixed;
top: 0;
left: 0;
height: 100%;
width: clamp(14em, 30vw, 20em);
background: #373d49;
color: #d0d6e2;
padding: 1.2em;
padding-left: 0;
overflow-y: scroll;
}
nav a:link { text-decoration: none }
nav a:link, a:visited { color: #d0d6e2 }
nav a:hover { color: #35d7bb }
nav ul {
list-style: none;
padding-left: 1.2em
}
nav li { margin-top: 0.4em }
/* Logo */
nav::before {
content: "GRAY";
text-align: center;
font-weight: bold;
font-size: 1.6em;
position: absolute;
left: calc(50% - 1.6em);
}
nav > ul { padding-top: 2em }