diff --git a/Makefile b/Makefile index 9f9849c..e3e42a2 100644 --- a/Makefile +++ b/Makefile @@ -8,16 +8,20 @@ # Structure: # gray - top level # ├── src - source code +# ├── doc - documentation # └── build - build artifacts # ├── bin - binaries # ├── lib - libraries # └── obj - objects SRCDIR = src BUILDDIR = build +SHAREDIR = build/share BINDIR = build/bin LIBDIR = build/lib OBJDIR = build/obj -DIRS = $(BINDIR) $(OBJDIR) $(LIBDIR) + +# Directories that need to be created +DIRS = $(BINDIR) $(OBJDIR) $(LIBDIR) $(SHAREDIR) ## ## Files @@ -71,18 +75,20 @@ endif ## Targets ## -.PHONY: all clean install +.PHONY: all clean install docs -all: $(BINARIES) $(LIBRARIES) +all: $(BINARIES) $(LIBRARIES) docs # Remove all generated files clean: rm -r $(BUILDDIR) -# Install libraries, binaries and man pages +# Install libraries, binaries and documentation install: $(BINARIES) $(LIBRARIES) doc/gray.1 install -Dm555 -t $(PREFIX)/bin $(BINDIR)/* 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 # GRAY binary @@ -97,6 +103,11 @@ $(LIBGRAY).so: $(MODULES) | $(LIBDIR) $(LIBGRAY).a($(MODULES)): | $(LIBDIR) $(LIBGRAY).a: $(LIBGRAY).a($(MODULES)) +# All documentation +docs: | $(SHAREDIR) + make -C doc + cp -t $(SHAREDIR) -r doc/build/* + # Visualise the dependency graph # Note: requires makefile2graph and graphviz graph.svg: Makefile diff --git a/configure b/configure index f34ffff..91b9416 100755 --- a/configure +++ b/configure @@ -15,6 +15,7 @@ Options: --prefix=PREFIX install files in PREFIX [/usr/local] --enable-static statically link programs and libraries [no] --disable-static dynamically link programs and libraries [yes] + --with-katex=PATH specify path to the KaTeX library [automatically downloaded] EOF } @@ -26,6 +27,9 @@ check() { return $? } +# Truncate the current configuration +: > configure.mk + # Parse command line options for arg in "$@"; do case "$arg" in @@ -36,6 +40,7 @@ for arg in "$@"; do ;; --enable-static) printf 'STATIC=1\n' >> configure.mk ;; --disable-static) ;; + --with-katex=*) printf 'KATEX_URL==file://%s/\n' "${arg#*=}" >> configure.mk ;; *=*) printf '%s\n' "${arg?}" >> configure.mk printf 'set %s\n' "$arg" @@ -44,9 +49,6 @@ for arg in "$@"; do esac done -# Truncate the current configuration -: > configure.mk - # Platform information printf 'Running on ' case $(uname -s) in diff --git a/default.nix b/default.nix index d675e86..2b6d8f7 100644 --- a/default.nix +++ b/default.nix @@ -8,6 +8,12 @@ let 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 source = builtins.filterSource (path: type: @@ -22,12 +28,31 @@ in version = "0.1"; 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; hardeningDisable = [ "format" ]; configureFlags = [ (lib.enableFeature static "static") + "--with-katex=${katex}" "GIT_REV=${version}" "GIT_DIRTY=" ]; diff --git a/doc/1.intro.md b/doc/1.intro.md new file mode 100644 index 0000000..6ec45c0 --- /dev/null +++ b/doc/1.intro.md @@ -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. diff --git a/doc/2.physics.md b/doc/2.physics.md new file mode 100644 index 0000000..04851e9 --- /dev/null +++ b/doc/2.physics.md @@ -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. diff --git a/doc/3.io-files.md b/doc/3.io-files.md new file mode 100644 index 0000000..3f70230 --- /dev/null +++ b/doc/3.io-files.md @@ -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} diff --git a/doc/4.implementation.md b/doc/4.implementation.md new file mode 100644 index 0000000..0a52b83 --- /dev/null +++ b/doc/4.implementation.md @@ -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} +$$ diff --git a/doc/5.changelog.md b/doc/5.changelog.md new file mode 100644 index 0000000..5bf12d3 --- /dev/null +++ b/doc/5.changelog.md @@ -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} diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..e49236c --- /dev/null +++ b/doc/Makefile @@ -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 $@ diff --git a/doc/res/style.csl b/doc/res/style.csl new file mode 100644 index 0000000..135329d --- /dev/null +++ b/doc/res/style.csl @@ -0,0 +1,149 @@ + + diff --git a/doc/res/style.css b/doc/res/style.css new file mode 100644 index 0000000..8857bbf --- /dev/null +++ b/doc/res/style.css @@ -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 }