Merge branch 'master' of github.com:gafusion/doc

docs/_sources/build.rst.txt

@@ -0,0 +1,78 @@
+Build on your laptop
+====================
+
+First step
+----------
+
+You will need suitable python and fortran environments. There is detailed help for
+
+* :doc:`OSX users <build/pre_osx>` (MAC M2)
+* :doc:`Linux users <build/pre_linux>` (MINT, UBUNTU)
+
+If you need more help, please raise an issue at https://github.com/gafusion/gacode/issues
+
+Source code
+-----------
+
+You should clone the gacode repository from GitHub. This was you can keep you installation up to date::
+
+  $ git clone [email protected]:gafusion/gacode.git
+
+Concept of platform files
+-------------------------
+
+In order to compile the full GACODE package on a new machine, **platform files** must be created. You can use existing ones or create your own.  After cloning the repository, you can query the existing platforms using::
+
+  $ ./gacode/shared/bin/gacode_platforms 
+
+To create new platform files (say, for a new platform MINE) then copy/edit the following files::
+
+  $GACODE_ROOT/platform/build/make.inc.MINE
+  $GACODE_ROOT/platform/exec/exec.MINE
+  $GACODE_ROOT/platform/env/env.MINE (if needed)
+
+Numerous templates for each of these files can be found in the specific folders, and most often there will be an existing machine files that is almost exactly what you need
+
+Environment variables
+---------------------
+
+To use your new platform files, enter the following lines in your shell RC file::
+  
+  export GACODE_PLATFORM=MINE
+  export GACODE_ROOT=$HOME/gacode
+  . $GACODE_ROOT/shared/bin/gacode_setup
+  . $GACODE_ROOT/platform/env/env.MINE (if needed)
+
+OpenBLAS
+--------
+
+When building with gfortran, we recommend using `OpenBLAS <https://github.com/xianyi/OpenBLAS.git>`_. It is important to build with **single-threaded** settings. In the Makefile.rule file in the top-level OpenBLAS directory, set::
+
+   BINARY=64
+   USE_THREAD=0
+   USE_LOCKING=1
+   NO_SHARED=1
+   NO_CBLAS=1
+   NO_LAPACKE=1
+
+You can find an example of linking to OpenBLAS in the `MINT platform file <https://github.com/gafusion/gacode/blob/master/platform/build/make.inc.MINT>`_. To test the thread safety, you can use the test program in shared/hybridtest::
+
+   $ cd gacode/shared/hybridtest
+   $ make clean ; make
+   $ ./test
+
+Building
+--------
+
+To build the entire GACODE project, type::
+
+  $ cd $GACODE_ROOT ; make
+
+To test that the build is successful, you can run regression tests::
+
+  $ neo -r
+  $ tglf -r
+  $ cgyro -r -n 4 -nomp 2
+
+This last command run the complete CGYRO regression test suite using 4 MPI tasks and 2 OpenMP threads (8 total threads).
+

docs/_sources/build/pre_linux.rst.txt

@@ -0,0 +1,8 @@
+Ubuntu/Mint
+-----------
+
+Install fortran, MPICH and FFTW libraries::
+
+  $ sudo apt install gfortran
+  $ sudo apt install mpich libmpich-dev
+  $ sudo apt install libfftw3-dev

docs/_sources/build/pre_osx.rst.txt

@@ -0,0 +1,28 @@
+OSX Sonoma
+----------
+
+Install the Xcode command line developer tools::
+
+  $ xcode-select --install
+
+Download and Install Xquartz: https://www.xquartz.org   
+
+Download and Install Macports: https://www.macports.org/install.php::
+        
+  $ sudo port -v selfupdate
+
+Install python::
+
+  $ sudo port install python-310
+  $ sudo port select --set python python-310   
+  $ sudo port select --set python3 python-310   
+ 
+Install compilers::
+ 
+  $ sudo port install gcc13 
+  $ sudo port select --set gcc mp-gcc13     
+  $ sudo port install mpich-gcc13
+  $ sudo port select --set mpi mpich-gcc13-fortran
+  $ sudo port install fftw-3 
+  $ sudo port install netcdf
+  $ sudo port install netcdf-fortran

docs/_sources/cgyro.rst.txt

@@ -0,0 +1,108 @@
+CGYRO
+=====
+
+Brief description
+-----------------
+
+CGYRO is a global-spectral gyrokinetic code. Core developers are
+
+* Emily Belli, `General Atomics <https://www.ga.com/>`_ 
+* Jeff Candy, `General Atomics <https://www.ga.com/>`_
+* Klaus Hallatschek, `IPP <https://www.ipp.mpg.de/>`_ 
+* Igor Sfiligoi, `SDSC <https://www.sdsc.edu/>`_ 
+
+Simulation images
+-----------------
+
+Simulation data courtesy Nathan Howard (MIT)
+
+.. image:: cgyro/figures/b250.png
+	:width: 48 %
+	:alt: b250
+.. image:: cgyro/figures/b990.png
+	:width: 48 %
+	:alt: b990
+.. image:: cgyro/figures/b1020.png
+	:width: 48 %
+	:alt: b1020
+.. image:: cgyro/figures/b1480.png
+	:width: 48 %
+	:alt: b1480
+
+Source Code
+-----------
+
+`CGYRO source code <http://github.com/gafusion/gacode>`_  is available at GitHub.
+
+Past and Future
+---------------
+
+**The past: GYRO**
+
+Over the past two decades, the fusion community has focused its modeling efforts
+primarily on the core region. A popular kinetic code used for this purpose
+was GYRO :cite:`candy:2003,candy:2003b,candy:2004a,candy:2010`.
+Thousands of nonlinear simulations with GYRO have informed the fusion community's understanding of
+core plasma turbulence :cite:`kinsey:2005,kinsey:2006,kinsey:2007,howard:2016b`
+and provided a *transport database* for the calibration of reduced transport models
+such as TGLF :cite:`staebler:2007`.  GYRO was the first global electromagnetic solver,
+and pioneered the development of numerical algorithms for the GK equations
+with kinetic electrons.  It is formulated in real space and like all global solvers
+requires *ad hoc* absorbing-layer boundary conditions when simulating cases
+with profile variation.  This approach is suitable for core turbulence simulations,
+which cover a large radial region and are dominated by low wavenumbers.
+
+**The future: CGYRO**
+
+As the understanding of core transport has become increasingly complete, the
+cutting edge of research moved radially toward the pedestal region, where plasmas are
+characterized by larger collisionality and steeper pressure gradients that
+greatly modify the turbulent phenomena at play. This motivated the development,
+from scratch, of the CGYRO code :cite:`candy:2016,belli:2017,belli:2018,candy:2019`
+to complement GYRO.  CGYRO is an Eulerian GK solver specifically designed and
+optimized for **collisional, electromagnetic, multiscale simulation**.
+A key algorithmic aspect of CGYRO is the **radially spectral formulation**
+used to reduce the complicated integral gyroaveraging kernel into a
+multiplication in wavenumber space, but retaining the ability to treat profile
+variation important for edge plasmas :cite:`candy:2018,candy:2020`.  A new coordinate system that is more
+suitable for the highly collisional and shaped edge regime was adopted from
+the NEO code :cite:`belli:2008,belli:2012`, which is the community standard for
+calculation of collisional transport in toroidal geometry.
+
+
+Data input 
+----------
+
+* :doc:`Tabular list <cgyro/cgyro_table>`
+* :doc:`Alphabetical list <cgyro/cgyro_list>`
+* Profile data: :ref:`input.gacode`.
+
+Data output and plotting
+------------------------
+
+Although there is a description of :doc:`output data <cgyro/outputs>`, it is suggested that users use the python interface to output data.
+
+Normalization
+-------------
+
+.. csv-table:: **CGYRO Normalization**
+   :header: "Quantity", "Unit", "Description"
+   :widths: 16, 12, 20	 
+
+   length, :math:`a`, minor radius
+   mass, :math:`m_\mathrm{D}`, deuterium mass = :math:`3.345\times 10^{24} g`
+   density, :math:`n_e`, electron density
+   temperature, :math:`T_e`, electron temperature 
+   velocity, :math:`c_s = \sqrt{T_e/m_\mathrm{D}}`, deuterium sound speed
+   time, :math:`a/c_s`, minor radius over sound speed
+
+Running Cases
+-------------
+
+* :doc:`running cases <cgyro/running_cases>`
+
+Frequently Asked Questions
+--------------------------
+
+* :doc:`FAQ <cgyro/FAQ>`
+

docs/_sources/cgyro/FAQ.rst.txt

@@ -0,0 +1,63 @@
+FAQ
+===
+
+.. toggle-header::
+   :header: What is :math:`k_y \rho_s` and why does CGYRO modify :math:`\rho_s` ?
+
+	    The fundamental definition of the wavenumber and unit gyroradius are given in :cite:`candy:2016`.
+	    These are
+
+	    .. math:: \begin{align}
+		      k_y \doteq &~nq/r \; , \\
+		      \rho_s \doteq &~\rho_{s,\rm{unit}} = \frac{e B_\rm{unit}}{m_D c} \; , \\
+		      B_\rm{unit} \doteq &~\displaystyle \frac{q}{r} \frac{\partial \psi}{\partial r} \; .
+		      \end{align}
+
+            Here, :math:`B_\rm{unit}` is the *Waltz effective magnetic field* which is standard
+	    across all GACODE tools/codes, and :math:`r` is the midplane minor radius.  For a given
+	    value of :math:`k_y \rho_s`, the gyrokinetic equations are invariant to the scaling
+	    :math:`n \rightarrow \alpha n` and :math:`\rho_s \rightarrow \rho_s/\alpha`,
+	    where :math:`\alpha` is an arbitrary scaling parameter.
+
+            The CGYRO input parameter KY is
+
+	    .. math:: \mathtt{KY} \doteq \Delta(k_y \rho_s) = \Delta n \left(\frac{q}{r}\right) \rho_s \; .
+
+            CGYRO enforces :math:`\Delta n = 1`, which sets the (artificial) value of :math:`\rho_s` to
+
+	    .. math:: \rho_s \rightarrow \left(\frac{r}{q}\right) \mathtt{KY} \; .
+
+	    To see the physical values of key parameters, you can use profiles_gen:
+
+	    .. code-block:: 
+
+	       $ profiles_gen -i input.gacode -loc_rad 0.6
+	       INFO: (profiles_gen) input.gacode is autodetected as GACODE.
+	       INFO: (locpargen) Quasineutrality NOT enforced.
+	       INFO: (locpargen) rhos/a   =+2.44577E-03
+	       INFO: (locpargen) Te [keV] =+8.81550E-01
+	       INFO: (locpargen) Ti [keV] =+7.58644E-01
+	       INFO: (locpargen) Bunit    =+2.92020E+00
+	       INFO: (locpargen) beta_*   =+4.84003E-03
+	       INFO: ----->  n=1: ky*rhos =-7.74754E-03
+	       INFO: (locpargen) Wrote input.*.locpargen
+
+		      
+.. toggle-header::
+   :header: How does adaptive time-stepping work?
+
+	    Time-stepping is controlled with the parameter :ref:`cgyro_delta_t_method`. Setting the parameter
+	    to 0 gives the legacy fixed timestep, whereas values greater than 0 are adaptive methods. For the
+	    adaptive methods we recommend setting :ref:`cgyro_delta_t` = 0.01. Here is the recommendation:
+
+	    .. code-block:: 
+
+	       DELTA_T_METHOD=1
+	       DELTA_T=0.01
+	       PRINT_STEP=100
+
+	    The overall time-integration step is split between an explicit high-order step, and an implicit
+	    second-order step for collisions and trapping. When using the adaptive method, the value of
+	    :ref:`cgyro_delta_t` is the size of the (large) implicit timestep. Then, the value of the explicit
+	    timestep is decreased to match the error tolerance, :ref:`cgyro_error_tol` -- the default value of
+	    which should be sufficient.