From 5435d8cce7426267057b25a331cd363a19a2872d Mon Sep 17 00:00:00 2001 From: Nick Nelson Date: Wed, 14 Sep 2022 14:41:29 -0600 Subject: [PATCH 1/5] New Outline - Getting Started, Physics, Setup Creation of the first three sections of the new user guide structure as planned at 2022 Hack-a-thon. --- doc/source/User_Guide/getting_started.rst | 329 ++++++++++ doc/source/User_Guide/model_setup.rst | 609 ++++++++++++++++++ .../User_Guide/physics_math_overview.rst | 465 +++++++++++++ 3 files changed, 1403 insertions(+) create mode 100644 doc/source/User_Guide/getting_started.rst create mode 100644 doc/source/User_Guide/model_setup.rst create mode 100644 doc/source/User_Guide/physics_math_overview.rst diff --git a/doc/source/User_Guide/getting_started.rst b/doc/source/User_Guide/getting_started.rst new file mode 100644 index 00000000..38101095 --- /dev/null +++ b/doc/source/User_Guide/getting_started.rst @@ -0,0 +1,329 @@ +.. raw:: latex + + \clearpage + +.. _getting_started: + +Getting Started +================================= + +Accessing Rayleigh +------------------ + + +Installing Rayleigh +------------------- + + +A detailed explanation of the installation process may be found in the +root directory of the code repository at: + + Rayleigh/INSTALL. + +We provide an abbreviated version of those instructions here. + +Third-Party Dependencies +------------------------ + +In order to compile Rayleigh, you will need to have MPI (Message Passing +Interface) installed along with a Fortran 2003-compliant compiler. +Rayleigh has been successfully compiled with GNU, Intel, IBM, AOCC, and +Cray compilers (PGI has not been tested yet). Rayleigh’s configure script +provides native support for the Intel, GNU, AOCC, and Cray compilers. See +Rayleigh/INSTALL for an example of configuration using the IBM compiler. + +Rayleigh depends on the following third party libraries: + +#. BLAS (Basic Linear Algebra Subprograms) + +#. LAPACK (Linear Algebra PACKage) + +#. FFTW 3.x (Fastest Fourier Transform in the West) + +You will need to install these libraries before compiling Rayleigh. If +you plan to run Rayleigh on Intel processors, we suggest installing +Intel’s Math Kernel Library (MKL) in lieu of installing these libraries +individually. The Math Kernel Library provides optimized versions of +BLAS, LAPACK, and FFTW. It has been tuned, by Intel, for optimal +performance on Intel processors. At the time of this writing, MKL is +provided free of charge. You may find it +`here `__. + +Compilation +----------- + +Rayleigh is compiled using the standard Linux installation scheme of +configure/make/make-install. From within the Rayleigh directory, run +these commands: + +#. **./configure** – See Rayleigh/INSTALL or run ./configure --help to + see relevant options. + +#. **make** – This produces the code. You can run **make -j** to build several + files in parallel and speed up the build this way. + +#. **make install** – This places the Rayleigh executables in + Rayleigh/bin. If you would like to place them in (say) + /home/my_rayleigh/bin, run configure as: **./configure + –prefix=/home/my_rayleigh**, i.e., the executables will be placed in the + **$(prefix)/bin** directory. + +For most builds, two executables will be created: rayleigh.opt and +rayleigh.dbg. Use them as follows: + +#. When running production jobs, use **rayleigh.opt**. + +#. If you encounter an unexpected crash and would like to report the + error, rerun the job with **rayleigh.dbg**. This version of the code + is compiled with debugging symbols. It will (usually) produce + meaningful error messages in place of the gibberish that is output + when rayleigh.opt crashes. + +If *configure* detects the Intel compiler, you will be presented with a +number of choices for the vectorization option. If you select *all*, +rayleigh.opt will not be created. Instead, rayleigh.sse, rayleigh.avx, +etc. will be placed in Rayleigh/bin. This is useful if running on a +machine with heterogeneous node architectures (e.g., Pleiades). If you +are not running on such a machine, pick the appropriate vectorization +level, and rayleigh.opt will be compiled using that vectorization level. + +The default behavior of the **make** command is to build both the +optimized, **rayleigh.opt**, and the debug versions, **rayleigh.dbg**. As +described above, if Intel is used and *all* is selected, every version will +be compiled. To build only a single version, the **target=** option +may be used at the **make** stage, for example: + +#. **make target=opt** - build only the optimized version, **rayleigh.opt** + +#. **make target=dbg** - build only the debug version, **rayleigh.dbg** + +#. **make target=avx** - build only the AVX version, **rayleigh.avx** + +When building a single target, the final name of the executable can be changed +with the **output=** option during the **make install** command. For example, +to build the optimized version and name the executable **a.out**: + +#. **make target=opt** - only build the optimized version + +#. **make target=opt output=a.out install** - install the optimized version as **a.out** + +Inspection of the **$(prefix)/bin** directory (specified at configure time with the -prefix +option) will show a new file named **a.out**. + +If both the optimized version and the debug version have already been built, they +can be renamed at install time as: + +#. **make** - build both optimized and debug version (or all versions) + +#. **make target=opt output=a.out.opt install** - install and rename the optimized version + +#. **make target=dbg output=a.out.dbg install** - install and rename the debug version + +The **output** option is only respected when a particular **target** is specified. Running +**make output=a.out install** will install all **rayleigh.*** executables, they will not +be renamed. + +Verifying Your Installation +--------------------------- + +Rayleigh comes with a benchmarking mode that helps you verify that the +installation is performing correctly. If you are running Rayleigh for +the first time, or running on a new machine, follow along with the +example in §\ :ref:`benchmarking`, that you receive an accurate benchmark report before running a custom +model. + +.. _spack-setup: + +Alternative: Installation using Spack +--------------------------------------- + +Spack is a package management tool designed to support multiple versions and +configurations of software on a wide variety of platforms and environments. It can be used to build Rayleigh with different compilers and a custom set of libraries for MPI, LAPACK, and FFTW. It can automatically build dependencies itself or use those provided by the HPC environment. + +To set up Spack in your environment follow the instructions in the `documentation `_. Add local `compilers `_ and `packages `_ as desired. + +The next step has only to be performed once to add the Rayleigh package repository. Run this from the base directory of the Rayleigh repository. + +.. code-block:: bash + + spack repo add spack-repo + +Afterwards you can just install Rayleigh and its dependencies using: + +.. code-block:: bash + + spack install rayleigh + +Once the build succeeded the package can be loaded using the following command, which will make the ``rayleigh.opt`` and ``rayleigh.dbg`` executables available in the ``PATH`` and can be run to start simulations as usual. + +.. code-block:: bash + + spack load rayleigh + +There are many ways in which to modify the compiler and dependencies being used. They can be found in the `Spack documentation `_. + +As an example you can install Rayleigh using MKL for LAPACK and FFTW using: + +.. code-block:: bash + + spack install rayleigh ^intel-mkl + +To see the dependencies being installed you can use: + +.. code-block:: bash + + spack spec rayleigh ^intel-mkl + +.. _benchmark: + +Running a Benchmark +------------------- + +Rayleigh has been programmed with internal testing suite so that its +results may be compared against benchmarks described in Christensen et al. (2001) +:cite:`CHRISTENSEN200125` and Jones et al. (2011) +:cite:`JONES2011120` + +We recommend running a benchmark whenever running Rayleigh on a new +machine for the first time, or after recompiling the code. The +Christensen et al. (2001) :cite:`CHRISTENSEN200125` reference describes two Boussinesq tests that +Rayleigh’s results may be compared against. The Jones et al. (2011) :cite:`JONES2011120` +reference describes anelastic tests. Rayleigh has been tested +successfully against two benchmarks from each of these papers. Input +files for these different tests are enumerated in Table table_benchmark_ +below. In addition to the +input files listed in Table table_benchmark_, +input examples appropriate for use as a template for new runs are +provided with the *\_input* suffix (as opposed to the *minimal* suffix. +These input files still have benchmark_mode active. Be sure to turn this +flag off if not running a benchmark. + + + +**Important:** If you are not running a benchmark, but only wish to +modify an existing benchmark-input file, delete the line containing the +text “*benchmark_mode=X*.” When benchmark mode is active, custom inputs, +such as Rayleigh number, are overridden and reset to their +benchmark-appropriate values. + +**We suggest using the c2001_case0_minimal input file for installation +verification**. Algorithmically, there is little difference between the +MHD, non-MHD, Boussinesq, and anelastic modes of Rayleigh. As a result, +when installing the code on a new machine, it is normally sufficient to +run the cheapest benchmark, case 0 from Christensen 2001 :cite:`CHRISTENSEN200125`. + +To run this benchmark, create a directory from within which to run your +benchmark, and follow along with the commands below. Modify the +directory structure a each step as appropriate: + +#. mkdir path_to_my_sim + +#. cd path_to_my_sim + +#. cp + path_to_rayleigh/Rayleigh/input_examples/c2001_case0_minimal   main_input + +#. cp path_to_rayleigh/Rayleigh/bin/rayleigh.opt   rayleigh.opt (or use + *ln -s* in lieu of *cp*) + +#. mpiexec -np **N** ./rayleigh.opt -nprow **X** -npcol **Y** -nr **R** + -ntheta **T** + +For the value **N**, select the number of cores you wish to run with. +For this short test, 32 cores is more than sufficient. Even with only +four cores, the lower-resolution test suggested below will only take +around half an hour. The values **X** and **Y** are integers that +describe the process grid. They should both be at least 2, and must +satisfy the expression + +.. math:: N=X \times Y. + +Some suggested combinations are {N,X,Y} = {32,4,8}, {16,4,4}, {8,2,4}, +{4,2,2}. The values **R** and **T** denote the number of radial and +latitudinal collocation points respectively. Select either {R,T}={48,64} +or {R,T}={64,96}. The lower-resolution case takes about 3 minutes to run +on 32 Intel Haswell cores. The higher-resolution case takes about 12 +minutes to run on 32 Intel Haswell cores. + +Once your simulation has run, examine the file +path_to_my_sim/Benchmark_Reports/00025000. You should see output similar +to that presented in Tables table_benchmark_low_ or table_benchmark_high_ . Your numbers may differ +slightly, but all values should have a % difference of less than 1. If +this condition is satisfied, your installation is working correctly. + +.. _table_benchmark: + +.. centered:: **Table. Benchmark.** + +Benchmark-input examples useful for verifying Rayleigh’s installation. +Those from Christensen et al. (2001) :cite:`CHRISTENSEN200125` +are Boussinesq. Those from Jones et al. (2011) :cite:`JONES2011120` are anelastic. Examples are found +in the directory: Rayleigh/input_examples/ + ++-----------------------+-----------------+--------------------------------+--------------------------------+ +| Paper | Benchmark | Input File | Specify in the main_input file | ++=======================+=================+================================+================================+ +| Christensen et al. | Case 0 | c2001_case0_minimal | benchmark_mode = 1 | ++-----------------------+-----------------+--------------------------------+--------------------------------+ +| Christensen et al. | Case 1(MHD) | c2001_case1_minimal | benchmark_mode = 2 | ++-----------------------+-----------------+--------------------------------+--------------------------------+ +| Jones et al. 2011 | Steady Hydro | j2011_steady_hydro_minimal | benchmark_mode = 3 | ++-----------------------+-----------------+--------------------------------+--------------------------------+ +| Jones et al. 2011 | Steady MHD | j2011_steady_MHD_minimal | benchmark_mode = 4 | ++-----------------------+-----------------+--------------------------------+--------------------------------+ + + +.. _table_benchmark_low: + +.. centered:: **Table. Benchmark Low.** + +Rayleigh benchmark report for Christensen +et al. (2001) :cite:`CHRISTENSEN200125` case 0 when run with nr=48 and ntheta=64. Run time was +approximately 3 minutes when run on 32 Intel Haswell cores. + +Run command: + +.. code-block:: + + mpiexec -np 32 ./rayleigh.opt -nprow 4 -npcol 8 -nr 48 -ntheta 64 + ++-----------------+------------+------------+--------------+-----------+ +| Observable | Measured | Suggested | % Difference | Std. Dev. | ++=================+============+============+==============+===========+ +| Kinetic Energy | 58.347827 | 58.348000 | -0.000297 | 0.000000 | ++-----------------+------------+------------+--------------+-----------+ +| Temperature | 0.427416 | 0.428120 | -0.164525 | 0.000090 | ++-----------------+------------+------------+--------------+-----------+ +| Vphi | -10.118053 | -10.157100 | -0.384434 | 0.012386 | ++-----------------+------------+------------+--------------+-----------+ +| Drift Frequency | 0.183272 | 0.182400 | 0.477962 | 0.007073 | ++-----------------+------------+------------+--------------+-----------+ + + +.. _table_benchmark_high: + + +.. centered:: **Table. Benchmark High.** + +Rayleigh benchmark report for Christensen +et al. (2001) :cite:`CHRISTENSEN200125` case 0 when run with nr=64 and ntheta=96. Run time was +approximately 12 minutes when run on 32 Intel Haswell cores. + +Run command: + +.. code-block:: + + mpiexec -np 32 ./rayleigh.opt -nprow 4 -npcol 8 -nr 64 -ntheta 96 + ++-----------------+------------+------------+--------------+-----------+ +| Observable | Measured | Suggested | % Difference | Std. Dev. | ++=================+============+============+==============+===========+ +| Kinetic Energy | 58.347829 | 58.348000 | -0.000294 | 0.000000 | ++-----------------+------------+------------+--------------+-----------+ +| Temperature | 0.427786 | 0.428120 | -0.077927 | 0.000043 | ++-----------------+------------+------------+--------------+-----------+ +| Vphi | -10.140183 | -10.157100 | -0.166551 | 0.005891 | ++-----------------+------------+------------+--------------+-----------+ +| Drift Frequency | 0.182276 | 0.182400 | -0.067994 | 0.004877 | ++-----------------+------------+------------+--------------+-----------+ + diff --git a/doc/source/User_Guide/model_setup.rst b/doc/source/User_Guide/model_setup.rst new file mode 100644 index 00000000..97b2d805 --- /dev/null +++ b/doc/source/User_Guide/model_setup.rst @@ -0,0 +1,609 @@ +.. raw:: latex + + \clearpage + +.. _model_setup: + +Setting Up a Model +================== + +This section details the basics of running a custom model +in Rayleigh. For a commplete list of all Rayleigh input +parameters, see :ref:`namelists`. + +.. _setup_prep: +Preparation +----------- + +Each simulation run using Rayleigh should have its own directory. The +code is run from within that directory, and any output is stored in +various subdirectories created by Rayleigh at run time. Wherever you +create your simulation directory, ensure that you have sufficient space +to store the output. + +**Do not run Rayleigh from within the source code directory. +Do not cross the beams: no running two models from within the same +directory.** + +After you create your run directory, you will want to copy (cp) or soft +link (ln -s ) the executable from Rayleigh/bin to your run directory. +Soft-linking is recommended; if you recompile the code, the executable +remains up-to-date. If running on an IBM machine, copy the script named +Rayleigh/etc/make_dirs to your run directory and execute the script. +This will create the directory structure expected by Rayleigh for its +outputs. This step is unnecessary when compiling with the Intel, GNU, +AOCC, or Cray compilers. + +Next, you must create a main_input file. This file contains the +information that describes how your simulation is run. Rayleigh always +looks for a file named main_input in the directory that it is launched +from. Copy one of the sample input files from the +Rayleigh/input_examples/ into your run directory, and rename it to +main_input. The file named *benchmark_diagnostics_input* can be used to +generate output for the diagnostics plotting tutorial (see +§\ :ref:`diagnostics`). + +Finally, Rayleigh has some OpenMP-related logic that is still in +development. We do not support Rayleigh’s OpenMP mode at this time, but +on some systems, it can be important to explicitly disable OpenMP in +order to avoid tripping any OpenMP flags used by external libraries, +such as Intel’s MKL. Please be sure and run the following command before +executing Rayleigh. This command should be precede *each* call to +Rayleigh. + +:: + + export OMP_NUM_THREADS=1 (bash) + setenv OMP_NUM_THREADS 1 (c-shell) + +.. _setup_grid: + +Grid Setup +---------- + +The number of radial grid points is denoted by +:math:`N_r`, and the number of :math:`\theta` grid points by +:math:`N_\theta`. The number of grid points in the :math:`\phi` +direction is always :math:`N_\phi=2\times N_\theta`. :math:`N_r` and +:math:`N_\theta` may each be defined in the problemsize_namelist of +main_input: + +:: + + &problemsize_namelist + n_r = 48 + n_theta = 96 + / + +:math:`N_r` and :math:`N_\theta` may also be specified at the command +line (overriding the values in main_input) via: + +:: + + mpiexec -np 8 ./rayleigh.opt -nr 48 -ntheta 96 + +If desired, the number of spherical harmonic degrees :math:`N_\ell` or the maximal spherical harmonic degree +:math:`\ell_\mathrm{max}\equiv N_\ell-1` may be specified in lieu of +:math:`N_\theta`. The example above may equivalently be written as + +:: + + &problemsize_namelist + n_r = 48 + l_max = 63 + / + +or + +:: + + &problemsize_namelist + n_r = 48 + n_l = 64 + / + +The radial domain bounds are determined by the namelist variables +``rmin`` (the lower radial boundary) and ``rmax`` (the upper +radial boundary): + +:: + + &problemsize_namelist + rmin = 1.0 + rmax = 2.0 + / + +Alternatively, the user may specify the shell depth (``rmax-rmin``) +and aspect ratio (``rmin/rmax``) in lieu of ``rmin`` and +``rmax``. The preceding example may then be written as: + +:: + + &problemsize_namelist + aspect_ratio = 0.5 + shell_depth = 1.0 + / + +Note that the interpretation of ``rmin`` and ``rmax`` depends on +whether your simulation is dimensional or nondimensional. We discuss +these alternative formulations in §\ :ref:`physics_math` + +It is possible to run Rayleigh with multiple, stacked domains in the +radial direction. Each of these is discretized using their own set of +Chebyshev polynomials. The boundaries and number of polynomials can be +set for each domain indiviadually, which makes it possible to control +the radial resolution at different radii. + +To use this feature the problem size has to be specified using +``domain_bounds`` and ``ncheby`` instead of ``rmin``, ``rmax``, and +``n_r``. ``ncheby`` takes a comma-separated list of the number of radial +points to use in each domain. ``domain_bounds`` takes a comma-separated +list of the radii of the domain boundaries, starting with the smallest +radius. It has one element more than the number of domains. This is an +example of two radial domains, one covering the radii 1 to 2 with 16 +radial points, the other the radii 2 to 4 with 64 radial points. + +:: + + &problemsize_namelist + domain_bounds = 1.0, 2.0, 4.0 + ncheby = 16, 64 + / + +Radial values in the diagnostic output will be repeated at the inner +domain boundaries. Most quantities are forced to be continuous at these +points. + +.. _numerical_controls: + +Numerical Controls +------------------ + +Rayleigh has several options that control aspects of the numerical method +used. For begining users these can generallly be left to default values. + + +.. _physics_controls: + +Physics Controls +---------------- + +Many physical effects can be turned on or off in Rayleigh. The details of +what physics you want to include will depend on the type of model you want +to run. Be careful, however, that if you are adapting an input file from +the benchmark described in :ref:`benchmark` that you set +:code:`benchmark_mode` to 0 or omit it entirely, as this will override +other input flags in favor of running the specified benchmark. For more +information on running benchmarks, see :ref:`cookbooks`. + +A number of logical variables can be used to turn certain physics on +(value = .true.) or off ( value = .false.). These variables are +described in Table table_logicals_, with default +values indicated in brackets. + + .. _table_logicals: + +.. centered:: **Table. Logicals.** + +Variables in the Physical_Controls_Namelist +that may be specified to control run behavior (defaults indicated in +brackets) + + +-----------------------------------+-----------------------------------+ + | Variable [Default value] | Description | + +===================================+===================================+ + | magnetism [.false.] | Turn magnetism on or off | + +-----------------------------------+-----------------------------------+ + | rotation [.false.] | Turn rotation on or off (pressure | + | | is not scaled by E when off) | + +-----------------------------------+-----------------------------------+ + | lorentz_forces [.true.] | Turn Lorentz forces on or off | + | | (magnetism must be .true.) | + +-----------------------------------+-----------------------------------+ + | viscous_heating [.true.] | Turn viscous heating on or off | + | | (inactive in Boussinesq mode) | + +-----------------------------------+-----------------------------------+ + | ohmic_heating [.true.] | Turn ohmic heating off or on | + | | (inactive in Boussinesq mode) | + +-----------------------------------+-----------------------------------+ + +.. _initial_conditions: + +Initial Conditions +------------------ + +A Rayleigh simulation may be initialized with a random thermal and/or +magnetic field, or it may be restarted from an existing checkpoint file +(see §\ :ref:`checkpointing` for a detailed +discussion of checkpointing). This behavior is controlled through the +**initial_conditions_namelist** and the **init_type** and +**magnetic_init_type** variables. The init_type variable controls the +behavior of the velocity and thermal fields at initialization time. +Available options are: + +- init_type=-1 ; read velocity and thermal fields from a checkpoint + file + +- init_type=1 ; Christensen et al. (2001) case 0 benchmark init ( + {:math:`\ell=4,m=4`} temperature mode) + +- init_type=6 ; Jones et al. (2011) steady anelastic benchmark ( + {:math:`\ell=19,m=19`} entropy mode) + +- init_type=7 ; random temperature or entropy perturbation + +- init_type=8 ; user generated temperature or entropy perturbation + (see Generic Initial Conditions below) + +When initializing a random thermal field, all spherical harmonic modes +are independently initialized with a random amplitude whose maximum +possible value is determined by the namelist variable **temp_amp**. The +mathematical form of of this random initialization is given by + +.. _eq_init: + +.. math:: + + T(r,\theta,\phi) = \sum_\ell \sum_m c_\ell^m f(r)g(\ell)\mathrm{Y}_\ell^m(\theta,\phi), + +where the :math:`c_\ell^m`\ ’s are (complex) random amplitudes, +distributed normally within the range [-temp_amp, temp_amp]. The radial +amplitude :math:`f(r)` is designed to taper off to zero at the +boundaries and is given by + +.. math:: f(r) = \frac{1}{2}\left[1-\mathrm{cos}\left( 2\pi\frac{r-rmin}{rmax-rmin} \right) \right]. + +The amplitude function :math:`g(\ell)` concentrates power in the +central band of spherical harmonic modes used in the simulation. It is +given by + +.. math:: g(\ell) = \mathrm{exp}\left[ - 9\left( \frac{ 2\,\ell-\ell_\mathrm{max} }{ \ell_\mathrm{max} } \right)^2 \right], + +which is itself, admittedly, a bit random. + +When initializing using a random thermal perturbation, it is important +to consider whether it makes sense to separately initialize the +spherically-symmetric component of the thermal field with a profile that +is in conductive balance. This is almost certainly the case when running +with fixed temperature conditions. The logical namelist variable +**conductive_profile** can be used for this purpose. It’s default value +is .false. (off), and its value is ignored completely when restarting +from a checkpoint. To initialize a simulation with a random temperature +field superimposed on a spherically-symmetric, conductive background +state, something similar to the following should appear in your +main_input file: + +:: + + &initial_conditions_namelist + init_type=7 + temp_amp = 1.0d-4 + conductive_profile=.true. + / + +Alternatively, you may wish to specify an ell=0 initial thermal profile +that is neither random nor conductive. To create your own profile, follow the example found in +Rayleigh/examples/custom_thermal_profile/custom_thermal_profile.ipynb. Then, use the following combination +of input parameters in main_input: + +:: + + &initial_conditions_namelist + init_type=7 + temp_amp = 1.0d-4 + custom_thermal_file = 'my_custom_profile.dat' + / + +This will use the radial profile stored in my_custom_profile.dat for the ell=0 component of entropy/temperature +Random values will be used to initialize all other modes. + +Magnetic-field initialization follows a similar pattern. Available +values for magnetic_input type are: + +- magnetic_init_type = -1 ; read magnetic field from a checkpoint file + +- magnetic_init_type = 1 ; Christensen et al. (2001) case 0 benchmark + init + +- magnetic_init_type = 7 ; randomized vector potential + +- magnetic_init_type=8 ; user generated magnetic potential fields + (see Generic Initial Conditions below) + +For the randomized magnetic field, both the poloidal and toroidal +vector-potential functions are given a random power distribution +described by Equation eq_init_. Each mode’s random +amplitude is then determined by namelist variable **mag_amp**. This +variable should be interpreted as an approximate magnetic field strength +(it’s value is rescaled appropriately for the poloidal and toroidal +vector potentials, which are differentiated to yield the magnetic +field). + +When initializing all fields from scratch, a main_input file should +contain something similar to: + +:: + + &initial_conditions_namelist + init_type=7 + temp_amp = 1.0d-4 + conductive_profile=.true. ! Not always necessary (problem dependent) ... + magnetic_init_type=7 + mag_amp = 1.0d-1 + / + + +.. _sec:generic_ic: + +Generic Initial Conditions +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The user can input any initial conditions from data files generated by +a python routine "rayleigh_spectral_input.py", which can be called as +a script or imported as a python class. + +The available generic initial conditions options are + +:: + + &initial_conditions_namelist + init_type=8 + T_init_file = '' !! Temperature + W_init_file = '' !! Poloidal velocity potential + Z_init_file = '' !! Toroidal velocity potential + P_init_file = '' !! `Pressure` potential + magneic_init_type=8 + C_init_file = '' !! Poloidal magnetic potential + A_init_file = '' !! Toroidal magnetic potential + + / + +where `T_init_file` is a user generated initial temperature field and + is the name of the file generated by the python script. If +`T_init_file` is not specified the initial field will be zero by +default. The same for the other fields. Fields T, W, Z, and P are +only initialized from the file if `init_type=8`. Fields C and A are +only initialized from file if `magnetic_init_type=8`. + +To generate a generic initial condition input file, for example, if a user wanted to specify a single mode in that input file then they could just run the script: + +:: + + rayleigh_spectral_input.py -m 0 0 0 1.+0.j -o example + + +to specify (n,l,m) = (0,0,0) to have a coefficient 1.+0.j and output it to the file example. + +This could also be done using the python as a module. In a python +shell this would look like: + +:: + + from rayleigh_spectral_input import * + si = SpectralInput() + si.add_mode(1., n=0, l=0, m=0) + si.write('example') + + +For a more complicated example, e.g. the hydrodynamic benchmark from +Christensen et al. 2001, the user can specify functions of theta, phi +and radius that the python will convert to spectral: + +:: + + rayleigh_spectral_input.py -ar 0.35 -sd 1.0 -nt 96 -nr 64 -o example \ + -e 'import numpy as np; x = 2*radius - rmin - rmax; + rmax*rmin/radius - rmin + 210*0.1*(1 - 3*x*x + 3*(x**4) - + x**6)*(np.sin(theta)**4)*np.cos(4*phi)/np.sqrt(17920*np.pi)' + +in "script" mode. + +Alternatively, in "module" mode in a python shell: + +:: + + from rayleigh_spectral_input import * + si = SpectralInput(n_theta=96, n_r=64) + rmin, rmax = radial_extents(aspect_ratio=0.35, shell_depth=1.0) + def func(theta, phi, radius): + x = 2*radius - rmin - rmax + return rmax*rmin/radius - rmin + 210*0.1*(1 - 3*x*x + 3*(x**4) - x**6)*(np.sin(theta)**4)*np.cos(4*phi)/np.sqrt(17920*np.pi) + si.transform_from_rtp_function(func, aspect_ratio=0.35, shell_depth=1.0) + si.write('example') + + +The above commands will generate a file called `example` which can be +called by + +:: + + &initial_conditions_namelist + init_type=8 + T_init_file = 'example' + +Note that these two examples will have produced different data formats - the first one sparse (listing only the mode specified) and the second one dense (listing all modes). + +For more examples including magnetic potentials see `tests/generic_input`. + +.. _boundary_conditions: + +Boundary Conditions & Internal Heating +-------------------------------------- + +Boundary conditions are controlled through the +**Boundary_Conditions_Namelist**. All Rayleigh simulations are run with +impenetrable boundaries. These boundaries may be either no-slip or +stress-free (default). If you want to employ no-slip conditions at both +boundaries, set **no_slip_boundaries = .true.**. If you wish to set +no-slip conditions at only one boundary, set **no_slip_top=.true.** or +**no_slip_bottom=.true.** in the Boundary_Conditions_Namelist. + +By default, magnetic boundary conditions are set to match to a potential field at +each boundary. + +By default, the thermal anomoly :math:`\Theta` is set to a fixed value +at each boundary. The upper and lower boundary-values are specified by +setting **T_top** and **T_bottom** respectively in the +Boundary_Conditions_Namelist. Their defaults values are 1 and 0 +respectively. + +Alternatively, you may specify a constant value of +:math:`\partial\Theta/\partial r` at each boundary. This is accomplished +by setting the variables **fix_dTdr_top** and **fix_dTdr_bottom**. +Values of the gradient may be enforced by setting the namelist variables +**dTdr_top** and **dTdr_bottom**. Both default to a value of zero. + +Generic Boundary Conditions +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Boundary conditions for temperature, :math:`T`, and the magnetic poloidal potential, :math:`C`, +may also be set using generic spectral input. As with initial conditions (see :ref:`sec:generic_ic`) +this is done by generating a generic input file using the **rayleigh_spectral_input.py** script. +The file output from this script can then be applied using: + +- **fix_Tvar_top** and **T_top_file** (overrides **T_top** for a constant boundary condition) + to set a fixed upper :math:`T` boundary condition +- **fix_dTdr_top** and **dTdr_top_file** (overrides **dTdr_top**) to set a fixed upper :math:`T` gradient boundary condition +- **fix_Tvar_bottom** and **T_bottom_file** (overrides **T_bottom**) to set a fixed lower :math:`T` boundary condition +- **fix_dTdr_bottom** and **dTdr_bottom_file** (overrides **dTdr_bottom**) to set a fixed lower :math:`T` gradient boundary + condition +- **fix_poloidal_top** and **C_top_file** (overrides **impose_dipole_field**) to set a fixed upper :math:`C` boundary condition +- **fix_poloidal_bottom** and **C_bottom_file** (overrides **impose_dipole_field**) to set a fixed lower :math:`C` boundary condition + +For example, to set a :math:`C` boundary condition on both boundaries with modes (l,m) = (1,0) and (1,1) set to pre-calculated +values run: + +:: + + rayleigh_spectral_input.py -m 1 0 2.973662220170157 -m 1 1 0.5243368809294343+0.j -o ctop_init_bc + rayleigh_spectral_input.py -m 1 0 8.496177771914736 -m 1 1 1.4981053740840984+0.j -o cbottom_init_bc + +which will generate generic spectral input files `ctop_init_bc` and `cbottom_init_bc`. Set these to be used as the boundary +conditions in `main_input` using: + +:: + + &Boundary_Conditions_Namelist + fix_poloidalfield_top = .true. + fix_poloidalfield_bottom = .true. + C_top_file = 'ctop_init_bc' + C_bottom_file = 'cbottom_init_bc' + / + +This can be seen being applied in `tests/generic_input`. + +Internal Heating +~~~~~~~~~~~~~~~~ + +The internal heating function :math:`Q(r)` is activated and described by +two variables in the **Reference_Namelist**. These are **Luminosity** +and **heating_type**. Note that these values are part of the +**Reference_Namelist** and not the **Boundary_Conditions** namelist. +Three heating types (0,1, and 4) are fully supported at this time. +Heating type zero corresponds to no heating. This is the default. + +**Heating_type=1:** This heating type is given by : + +.. math:: + + \label{eq:heating} + %\frac{\partial \Theta}{\partial t}=\gamma\left( 1 -\frac{\hat{\rho}(r_\mathrm{max})\,\hat{T}(r_\mathrm{max}) }{\hat{\rho}(r)\, \hat{T}(r)} \right), + Q(r)= \gamma\,\hat{\rho}(r)\, \hat{T}(r) + +where :math:`\gamma` is a normalization constant defined such that + +.. _eq_lum: + +.. math:: + + + %4\pi r_o^2 \hat{\rho}\hat{T}\kappa(r)\frac{\partial \Theta}{\partial r}=\mathrm{Luminosity} + 4\pi\int_{r=r_\mathrm{min}}^{r=r_\mathrm{max}} Q(r)\, r^2 dr = \mathrm{Luminosity}. + +This heating profile is particularly useful for emulating radiative +heating in a stellar convection zone. + +**Heating_type=4:** This heating type corresponds a heating that is +variable in radius, but constant in *energy density*. Namely + +.. math:: \hat{\rho}\hat{T}\frac{\partial \Theta}{\partial t}=\gamma. + +The constant :math:`\gamma` in this case is also set by enforcing +Equation eq_lum_. + +**Note:** If internal heating is used in combination with **fix_dTdr_top**, then the value of :math:`\partial\Theta/\partial r` +at the upper boundary is set by Rayleigh. Any value for **dTdr_top** specified in main_input is ignored. This is done to ensure consistency with the internal +heating and any flux passing through the lower boundary due +to the use of a fixed-flux condition. To override this behavior, set **adjust_dTdr_top** to .false. in the +**Boundary_Conditions** namelist. + +.. _output_controls: + +Output Controls +--------------- + +Rayleigh comes bundled with an in-situ diagnostics package that allows +the user to sample a simulation in a variety of ways, and at +user-specified intervals throughout a run. This package is comprised of +roughly 17,000 lines of code (about half of the Rayleigh code base). Here we will +focus on generating basic output, but we refer the user to the section +:ref:`plotting` and :ref:`quantityCodes` for more information. + +Rayleigh can compute the quanties listed in :ref:`quantityCodes` in a variety of +averages, slices, and spectra, which are collectively called data products. These +are sorted by Rayleigh into directories as +follows: + +* G_Avgs: The quantity is averaged over the entire simulation volume. +* Shell_Avgs: The quantity is averaged over each spherical shell and output as a function of radius. +* AZ_Avgs: The quantity is averaged over longitude and output as a function of radius and latitude. +* Shell_Slices: The quantity at the specified radii is output as a function of latitude and longitude. +* Equatorial_Slices: The quantity at the specified latitudes is output as a function of radius and longitude. +* Meridional_Slices: The quantity at the specified longitudes is output as a function of radius and latitude. +* Spherical_3D: The qunatity over the entire domain. Careful -- these files can be quite large. +* Shell_Spectra: The quantity's spherical harmonic coefficents at the specified radii. +* Point_Probes: The quantity at a specified radius, latitude, and longtiude. +* SPH_Mode_Sampels: The quantity's spherical harmonic coefficents at the specified radii and :math:`\ell`. + +In addition Rayleigh can output `Checkpoints`, which are the data required to restart +Rayleigh and will be discussed in detail in :ref:`checkpointing`, and `Timings`, which +contain information about the performance of the run. + +Output in Rayleigh is controled through the `io_controls_namelist`. For each of the data +products listed, the output is specified using the following pattern: + +* \_values: The quantity codes desired (seperated by commas) +* \_frequency: The frequency in iterations those quantities will be output. +* \_nrec: Number of records to be combined into a single file. +* \_levels: Radial indicies at which the quantities will be output. +* \_indices: Latitudinal indicies at which the quanties will be output. +* \_ell: The spherical harmonic degree at which the quantities will be output. +* \_r, \_theta, \_phi: The radial, latitudinal, and longitudinal indicies at which the quanties will be output. + +For example, if you wanted to output shell slice data for quantities 1, 2, 10, and 2711 at radial indicices 2 and 54 every 100 iterations and have 4 records per file, you would set + +:: + + shellslice_levels = 2,54 + shellslice_values = 1,2,10,2711 + shellslice_frequency = 100 + shellslice_nrec = 4 + +Files output in this way will have the filename of their iteration. + +.. _examples: + +Exampels from Recent Publications +--------------------------------- + +Need text here. + +.. _surveys: + +Setting Up a Survey +------------------- + +Need text here. + + + diff --git a/doc/source/User_Guide/physics_math_overview.rst b/doc/source/User_Guide/physics_math_overview.rst new file mode 100644 index 00000000..c5c97ff7 --- /dev/null +++ b/doc/source/User_Guide/physics_math_overview.rst @@ -0,0 +1,465 @@ +.. raw:: latex + + \clearpage + +.. _physics_math: + +The Physics and Mathematics of Rayleigh +======================================= + +Rayleigh solves the MHD equations in spherical geometry under the +Boussinesq and anelastic approximations. This section will provide a +basic overview of those equations as well as the mathematical approach +Rayleigh uses to solve them. + +The Equation Sets Solved by Rayleigh +------------------------------------ + +Rayleigh solves the Boussinesq or anelastic MHD equations in spherical +geometry. Both the equations that Rayleigh solves and its diagnostics +can be formulated either dimensionally or nondimensionally. A +nondimensional Boussinesq formulation, as well as dimensional and +nondimensional anelastic formulations (based on a polytropic reference +state) are provided as part of Rayleigh. The user may employ alternative +formulations via the custom Reference-state interface. To do so, they +must specify the functions :math:`\mathrm{f}_i` and the constants +:math:`c_i` in Equations :eq:`momentum`-:eq:`induction` at +input time (*in development*). + +The general form of the momentum equation solved by Rayleigh is given by + +.. math:: + :label: momentum + + \mathrm{f}_1(r)\left[\frac{\partial \boldsymbol{v}}{\partial t} + \boldsymbol{v}\cdot\boldsymbol{\nabla}\boldsymbol{v} %advection + + c_1\boldsymbol{\hat{z}}\times\boldsymbol{v} \right] =\ % Coriolis + &c_2\,\mathrm{f}_2(r)\Theta\,\boldsymbol{\hat{r}} % buoyancy + - c_3\,\mathrm{f}_1(r)\boldsymbol{\nabla}\left(\frac{P}{\mathrm{f}_1(r)}\right) % pressure + \\ + &+ c_4\left(\boldsymbol{\nabla}\times\boldsymbol{B}\right)\times\boldsymbol{B} % Lorentz Force + + c_5\boldsymbol{\nabla}\cdot\boldsymbol{\mathcal{D}}, + +where the stress tensor :math:`\mathcal{D}` is given by + +.. math:: + :label: stress_tensor + + \mathcal{D}_{ij} = 2\mathrm{f}_1(r)\,\mathrm{f}_3(r)\left[e_{ij} - \frac{1}{3}\left(\boldsymbol{\nabla}\cdot\boldsymbol{v}\right)\delta_{ij}\right]. +Here :math:`e_{ij}` and :math:`\delta_{ij}` refer to the standard rate-of-strain tensor and Kronecker delta, respectively. + +The velocity field is denoted by :math:`\boldsymbol{v}`, the thermal +anomoly by :math:`\Theta`, the pressure by :math:`P`, and the magnetic +field by :math:`\boldsymbol{B}`. All four of these quantities (eight, if you count the three components each for :math:`\boldsymbol{v}` and :math:`\boldsymbol{B}`) +are 3-dimensional functions of position, in contrast to the 1-dimensional +functions of radius :math:`\mathrm{f}_i(r)`. The velocity and magnetic +fields are subject to the constraints + +.. math:: + :label: v_constrain + + \boldsymbol{\nabla}\cdot\left[\mathrm{f}_1(r)\,\boldsymbol{v}\right] = 0 + +and + +.. math:: + :label: divB + + \boldsymbol{\nabla}\cdot\boldsymbol{B}=0, + +respectively. The evolution of :math:`\Theta` is described by + +.. math:: + :label: theta_evol + + \mathrm{f}_1(r)\,\mathrm{f}_4(r)\left[\frac{\partial \Theta}{\partial t} + \boldsymbol{v}\cdot\boldsymbol{\nabla}\Theta + \mathrm{f}_{14}(r)v_r\right] =\ + c_6\,\boldsymbol{\nabla}\cdot\left[\mathrm{f}_1(r)\,\mathrm{f}_4(r)\,\mathrm{f}_5(r)\,\boldsymbol{\nabla}\Theta \right] \\ + +\ c_{10}\,\mathrm{f}_6(r) + + c_8\,\Phi(r,\theta,\phi) + + c_9\,\mathrm{f}_7(r)|\boldsymbol{\nabla}\times\boldsymbol{B}|^2, + +where the viscous heating :math:`\Phi` is given by + +.. math:: + :label: vischeat + + \Phi(r,\theta,\phi) = \mathcal{D}_{ij}e_{ij} &= 2\,\mathrm{f}_1(r)\mathrm{f}_3(r)\left[e_{ij}e_{ij} - \frac{1}{3}\left(\boldsymbol{\nabla}\cdot\boldsymbol{v}\right)^2\right] \\ + &= 2\,\mathrm{f}_1(r)\mathrm{f}_3(r)\left[e_{ij} - \frac{1}{3}\left(\boldsymbol{\nabla}\cdot\boldsymbol{v}\right)\delta_{ij}\right]^2. + +Finally, the evolution of :math:`\boldsymbol{B}` is described by the +induction equation + +.. math:: + :label: induction + + \frac{\partial \boldsymbol{B}}{\partial t} = \boldsymbol{\nabla}\times\left[\boldsymbol{v}\times\boldsymbol{B} - c_7\,\mathrm{f}_7(r)\boldsymbol{\nabla}\times\boldsymbol{B}\,\right]. + +Note that when Rayleigh actually solves the equations, the following additional derivative functions are used: + +.. math:: + \mathrm{f}_8(r) &= \frac{d\ln{\mathrm{f}_1}}{dr}\\ + \mathrm{f}_9(r) &= \frac{d^2\ln{\mathrm{f}_1}}{dr^2}\\ + \mathrm{f}_{10}(r) &= \frac{d\ln{\mathrm{f}_4}}{dr}\\ + \mathrm{f}_{11}(r) &= \frac{d\ln{\mathrm{f}_3}}{dr}\\ + \mathrm{f}_{12}(r) &= \frac{d\ln{\mathrm{f}_5}}{dr}\\ + \mathrm{f}_{13}(r) &= \frac{d\ln{\mathrm{f}_7}}{dr}. + +When supplying a custom reference state, the user may specify the six derivative functions "by hand." If the user fails to do so, Rayleigh will compute the required derivatives (only if the user supplies the function whose derivative is to be taken) from the function's Chebyshev coefficients. + +Note that equations :eq:`momentum`-:eq:`induction` could have been formulated in other ways. For instance, we could combine +:math:`\mathrm{f}_1` and :math:`\mathrm{f}_3` into a single function in +Equation :eq:`vischeat`. The form of the equations +presented here has been chosen to reflect that actually used in the +code, which was originally written dimensionally. + +We now describe the nondimensional Boussinesq, and dimensional/nondimensional anelastic formulations used in the code. + +Nondimensional Boussinesq Formulation of the MHD Equations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Rayleigh can be run using a nondimensional, Boussinesq formulation +of the MHD equations (**reference_type=1**). The nondimensionalization +employed is as follows: + +.. math:: + + \begin{aligned} + \mathrm{Length} &\rightarrow L &\;\;\;\; \mathrm{(Shell\; Depth)} \\ + \mathrm{Time} &\rightarrow \frac{L^2}{\nu_o} &\;\;\;\; \mathrm{(Viscous\; Timescale)}\\ + \mathrm{Temperature} &\rightarrow \Delta T&\;\;\;\; \mathrm{(Temperature\; Contrast\; Across\; Shell)} \\ + \mathrm{Magnetic\; Field} &\rightarrow \sqrt{\hat{\rho}\mu\eta_o\Omega_0} \\ + \mathrm{Reduced\; Pressure} &\rightarrow \nu_o\Omega_0&\;\;\; (\mathrm{[Thermodynamic\; Pressure]}/\hat{\rho}),\end{aligned} + +where :math:`\Omega_0` is the rotation rate of the frame, :math:`\hat{\rho}` +is the (constant) density of the fluid, :math:`\eta_o` is the magnetic diffusivity at the top of the domain (i.e., at :math:`r=r_o`), :math:`\nu_o` +is the kinematic viscosity at the top of the domain, and :math:`\mu` is the magnetic permeability. Note that in Gaussian units for vacuum, :math:`\mu=4\pi`. After nondimensionalizing, the following +nondimensional numbers appear in our equations: + +.. math:: + + \begin{aligned} + Pr &=\frac{\nu_o}{\kappa_o} &\;\;\;\;\;\; \mathrm{Prandtl\; Number} \\ + Pm &=\frac{\nu_o}{\eta_o} &\;\;\;\;\;\; \mathrm{Magnetic\; Prandtl\; Number} \\ + E &=\frac{\nu_o}{\Omega_0\,L^2} &\;\;\;\;\;\; \mathrm{Ekman\; Number} \\ + Ra &=\frac{\alpha g_o \Delta T\,L^3}{\nu_o\kappa_o} &\;\;\;\;\;\; \mathrm{Rayleigh\; Number},\end{aligned} + +where :math:`\alpha` is coefficient of thermal expansion, :math:`g_o` +is the gravitational acceleration at the top of the domain, and :math:`\kappa` is the thermal +diffusivity. Adopting this nondimensionalization is equivalent to +assigning the following to the functions :math:`\mathrm{f}_i(r)` and the constants :math:`c_i`: + +.. math:: + + \begin{aligned} + \mathrm{f}_1(r) &\rightarrow 1\; &c_1 &\rightarrow \frac{2}{E} \\ + \mathrm{f}_2(r) &\rightarrow \left(\frac{r}{r_o}\right)^n \; &c_2 &\rightarrow \frac{Ra}{Pr} \\ + \mathrm{f}_3(r) &\rightarrow \tilde{\nu}(r)\; &c_3 &\rightarrow \frac{1}{E}\\ + \mathrm{f}_4(r) &\rightarrow 1\; &c_4 &\rightarrow \frac{1}{E\,Pm} \\ + \mathrm{f}_5(r) &\rightarrow \tilde{\kappa}(r)\; &c_5 &\rightarrow 1 \\ + \mathrm{f}_6(r) &\rightarrow 0\; &c_6 &\rightarrow \frac{1}{Pr} \\ + \mathrm{f}_7(r) &\rightarrow \tilde{\eta}(r)\; &c_7 &\rightarrow \frac{1}{Pm} \\ + &\vdots &c_8&\rightarrow 0\\ + &\vdots &c_9&\rightarrow 0 \\ + \mathrm{f}_{14}(r)&\rightarrow 0\; &c_{10}&\rightarrow 0.\end{aligned} + +Here the tildes denote nondimensional radial profiles, e.g., :math:`\tilde{\nu}(r) = \nu(r)/\nu_o`. + +Our choice of :math:`\mathrm{f}_{14}(r)\rightarrow 0` sets the default atmosphere in non-dimensional Boussinesq to be neutrally stable. For other choices (i.e., convectively stable or unstable), one must use the custom-reference-state framework. + +Our choice of :math:`\mathrm{f}_2(r)` allows gravity to vary +with radius based on the value of the exponent :math:`n`, which has a +default value of :math:`0` in the code. Note also that our definition of +:math:`Ra` assumes fixed-temperature boundary conditions. We might specify fixed-flux boundary conditions and/or an internal heating +through a suitable choice :math:`c_{10}\mathrm{f}_6(r)`, in which case the +meaning of :math:`Ra` in our equation set changes, with :math:`Ra` +denoting a flux Rayleigh number instead. In addition, ohmic and viscous +heating, which do not appear in the Boussinesq formulation, are turned +off when this nondimensionalization is specified at runtime. When these +substitutions are made, Equations :eq:`momentum`-:eq:`induction` +transform as follows. + +.. math:: + + \begin{aligned} + \left[\frac{\partial \boldsymbol{v}}{\partial t} + \boldsymbol{v}\cdot\boldsymbol{\nabla}\boldsymbol{v} %advection + + \frac{2}{E}\boldsymbol{\hat{z}}\times\boldsymbol{v} \right] &= % Coriolis + \frac{Ra}{Pr}\left(\frac{r}{r_o}\right)^n\Theta\,\boldsymbol{\hat{r}} % buoyancy + - \frac{1}{E}\boldsymbol{\nabla}P % pressure + + \frac{1}{E\,Pm}\left(\boldsymbol{\nabla}\times\boldsymbol{B}\right)\times\boldsymbol{B} % Lorentz Force + + \boldsymbol{\nabla}\cdot\boldsymbol{\mathcal{D}}& \\ + % + % + \left[\frac{\partial \Theta}{\partial t} + \boldsymbol{v}\cdot\boldsymbol{\nabla}\Theta \right] &= + \frac{1}{Pr}\boldsymbol{\nabla}\cdot\left[\tilde{\kappa}(r)\boldsymbol{\nabla}\Theta\right] \\ % Diffusion + % + % + \frac{\partial \boldsymbol{B}}{\partial t} &= \boldsymbol{\nabla}\times\left[\boldsymbol{v}\times\boldsymbol{B} - \frac{1}{Pm}\tilde{\eta}(r)\boldsymbol{\nabla}\times\boldsymbol{B}\right]\\ + \mathcal{D}_{ij} &= 2\tilde{\nu}(r)e_{ij} \\ + % + % + \boldsymbol{\nabla}\cdot\boldsymbol{v}&=0\\ + \boldsymbol{\nabla}\cdot\boldsymbol{B}&=0 \end{aligned} + +Here :math:`\Theta` refers to the temperature (perturbation from the background) and :math:`P` to the reduced pressure (ratio of the thermodynamic pressure to the constant density). + +Dimensional Anelastic Formulation of the MHD Equations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When run in dimensional, anelastic mode (cgs units; **reference_type=2** +), the following values are assigned to the functions +:math:`\mathrm{f}_i` and the constants :math:`c_i`: + +.. math:: + + \begin{aligned} + \mathrm{f}_1(r) &\rightarrow \hat{\rho}(r)\; &c_1 &\rightarrow 2\Omega_0 \\ + \mathrm{f}_2(r) &\rightarrow \frac{\hat{\rho}(r)}{c_P}g(r)\; &c_2 &\rightarrow 1 \\ + \mathrm{f}_3(r) &\rightarrow \nu(r)\; &c_3 &\rightarrow 1\\ + \mathrm{f}_4(r) &\rightarrow \hat{T}(r)\; &c_4 &\rightarrow \frac{1}{4\pi} \\ + \mathrm{f}_5(r) &\rightarrow \kappa(r)\; &c_5 &\rightarrow 1 \\ + \mathrm{f}_6(r) &\rightarrow \frac{Q(r)}{L_*}\; &c_6 &\rightarrow 1 \\ + \mathrm{f}_7(r) &\rightarrow \eta(r)\; &c_7 &\rightarrow 1 \\ + &\vdots &c_8&\rightarrow 1\\ + &\vdots &c_9&\rightarrow \frac{1}{4\pi} \\ + \mathrm{f}_{14}(r)&\rightarrow \frac{d\hat{S}}{dr }&c_{10}&\rightarrow L_*.\end{aligned} + +Here :math:`\hat{\rho}(r)`, :math:`\hat{T}(r)`, and :math:`d\hat{S}/dr` are the spherically symmetric, time-independent reference-state +density, temperature, and entropy gradient, respectively. :math:`g(r)` is the gravitational +acceleration, :math:`c_P` is the specific heat at constant pressure, and +:math:`\Omega_0` is the frame rotation rate. The viscous, thermal, and +magnetic diffusivities (also assumed to be spherically symmetric and time-independent) are given by :math:`\nu(r)`, :math:`\kappa(r)`, and +:math:`\eta(r)`, respectively. Note that the entropy gradient term :math:`f_{14}(r)v_r` is only used in Equation :eq:`theta_evol` if **advect_reference_state=.true.**. Finally, :math:`Q(r)` is an internal heating +function; it might represent radiative heating or heating due to nuclear +fusion, for instance. In our convention, the volume integral of :math:`\mathrm{f}_6(r)` equals unity, and :math:`c_{10}` equals the **luminosity** or **heating_integral** :math:`L_*` specified in the main_input file. When using a custom reference state, this allows easy adjustment of the luminosity using the **override_constants** formalism, e.g., + +**override_constants(10) = T** + +**ra_constants(10) = 3.846d33** + +specified in the in the **reference_namelist**. + +Note that in the anelastic formulation, the +thermal variable :math:`\Theta` is interpreted as the entropy perturbation, +rather than the temperature perturbation. When these substitutions are made, +Equations :eq:`momentum`-:eq:`induction` transform as follows. + +.. math:: + + \begin{aligned} + \hat{\rho}(r)\left[\frac{\partial \boldsymbol{v}}{\partial t} +\boldsymbol{v}\cdot\boldsymbol{\nabla}\boldsymbol{v} %advection + +2\Omega_0\boldsymbol{\hat{z}}\times\boldsymbol{v} \right] =\; % Coriolis + &\frac{\hat{\rho}(r)}{c_P}g(r)\Theta\,\boldsymbol{\hat{r}} % buoyancy + +\hat{\rho}(r)\boldsymbol{\nabla}\left(\frac{P}{\hat{\rho}(r)}\right) % pressure + \\ + &+\frac{1}{4\pi}\left(\boldsymbol{\nabla}\times\boldsymbol{B}\right)\times\boldsymbol{B} % Lorentz Force + +\boldsymbol{\nabla}\cdot\boldsymbol{\mathcal{D}}\\ + % + % + \hat{\rho}(r)\,\hat{T}(r)\left[\frac{\partial \Theta}{\partial t} +\boldsymbol{v}\cdot\boldsymbol{\nabla}\Theta + v_r\frac{d\hat{S}}{dr}\right] =\; + &\boldsymbol{\nabla}\cdot\left[\hat{\rho}(r)\,\hat{T}(r)\,\kappa(r)\,\boldsymbol{\nabla}\Theta \right] % diffusion + +Q(r) % Internal heating + \\ &+\Phi(r,\theta,\phi) + +\frac{\eta(r)}{4\pi}\left[\boldsymbol{\nabla}\times\boldsymbol{B}\right]^2\\ % Ohmic Heating + % + % + \frac{\partial \boldsymbol{B}}{\partial t} =\; &\boldsymbol{\nabla}\times\left[\,\boldsymbol{v}\times\boldsymbol{B}-\eta(r)\boldsymbol{\nabla}\times\boldsymbol{B}\,\right] \\ + % + % + \mathcal{D}_{ij} =\; &2\hat{\rho}(r)\,\nu(r)\left[e_{ij}-\frac{1}{3}\left(\boldsymbol{\nabla}\cdot\boldsymbol{v}\right)\delta_{ij}\right] \\ + % + % + \Phi(r,\theta,\phi) =\; &2\,\hat{\rho}(r)\nu(r)\left[e_{ij}e_{ij}-\frac{1}{3}\left(\boldsymbol{\nabla}\cdot\boldsymbol{v}\right)^2\right] \\ + % + % + \boldsymbol{\nabla}\cdot\left[\hat{\rho}(r)\,\boldsymbol{v}\right] =\; &0 \\ + \boldsymbol{\nabla}\cdot\boldsymbol{B} =\; &0. \end{aligned} + +Nondimensional Anelastic MHD Equations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To run in nondimensional anelastic mode, you must set +**reference_type=3** in the Reference_Namelist. The reference state is +assumed to be polytropic with a :math:`\frac{1}{r^2}` profile for +gravity. When this mode is +active, the following nondimensionalization is used +(following `Heimpel et al., 2016, Nat. Geo., 9, 19 `_ ): + +.. math:: + + \begin{aligned} + \mathrm{Length} &\rightarrow L \equiv r_o - r_i &\;\;\;\; \mathrm{(Shell\; Depth)} \\ + \mathrm{Time} &\rightarrow \frac{1}{\Omega_0} &\;\;\;\; \mathrm{(Rotational\; Timescale)}\\ + \mathrm{Temperature} &\rightarrow T_o\equiv\hat{T}(r_o)&\;\;\;\; \mathrm{(Reference\; Temperature\; at\; Upper\; Boundary)} \\ + \mathrm{Density} &\rightarrow \rho_o\equiv\hat{\rho}(r_o)&\;\;\;\; \mathrm{(Reference\; Density\; at\; Upper\; Boundary)} \\ + \mathrm{Entropy} &\rightarrow \Delta{s}&\;\;\;\; \mathrm{(Entropy\; Constrast\; Across\; Shell)} \\ + \mathrm{Magnetic~Field} &\rightarrow \sqrt{\hat{\rho}_o\mu\eta_o\Omega_0} \\ + \mathrm{Pressure} &\rightarrow \rho_oL^2\Omega_0^2.\end{aligned} + +When run in this mode, Rayleigh employs a polytropic background state, +with an assumed :math:`\frac{1}{r^2}` variation in gravity. These +choices result in the functions :math:`\mathrm{f}_i` and the constants +:math:`c_i` (tildes indicate nondimensional reference-state variables): + +.. math:: + + \begin{aligned} + \mathrm{f}_1(r) &\rightarrow \tilde{\rho}(r)\; &c_1 &\rightarrow 2 \\ + \mathrm{f}_2(r) &\rightarrow \tilde{\rho}(r)\frac{r_\mathrm{max}^2}{r^2}\; &c_2 &\rightarrow \mathrm{Ra}^* \\ + \mathrm{f}_3(r) &\rightarrow \tilde{\nu}(r)\; &c_3 &\rightarrow 1\\ + \mathrm{f}_4(r) &\rightarrow \tilde{T}(r)\; &c_4 &\rightarrow \frac{\mathrm{E}}{\mathrm{Pm}} \\ + \mathrm{f}_5(r) &\rightarrow \tilde{\kappa}(r)\; &c_5 &\rightarrow \mathrm{E} \\ + \mathrm{f}_6(r) &\rightarrow \frac{\tilde{Q}(r)}{L_*}; &c_6 &\rightarrow \frac{\mathrm{E}}{\mathrm{Pr}} \\ + \mathrm{f}_7(r) &\rightarrow \tilde{\eta}(r) \; &c_7 &\rightarrow \frac{\mathrm{E}}{\mathrm{Pm}} \\ + &\vdots &c_8&\rightarrow \frac{\mathrm{E}\,\mathrm{Di}}{\mathrm{Ra}^*}\\ + &\vdots &c_9&\rightarrow \frac{\mathrm{E}^2\,\mathrm{Di}}{\mathrm{Pm}^2\mathrm{Ra}^*}\\ + \mathrm{f}_{14}(r)&\rightarrow \frac{d\tilde{S}}{dr }&c_{10}&\rightarrow L_*.\end{aligned} + +As in the Boussinesq case, the nondimensional diffusivities are defined according to, e.g., :math:`\tilde{\nu}(r) \equiv \nu(r)/\nu_o`. The nondimensional heating :math:`\tilde{Q}(r)` is defined such that its volume integral equals the nondimensional **luminosity** or **heating_integral** set in the *main_input* file. As in the dimensional anelastic case, the volume integral of :math:`\mathrm{f}_6(r)` equals unity, and :math:`\mathrm{c}_{10} = L_*`. The unit for luminosity in this nondimensionalization (to get a dimensional luminosity from the nondimensional :math:`L_*`) is :math:`\rho_oL^3T_o\Delta s\Omega_0`. + +Two new nondimensional numbers appear in our equations, in addition to those defined for the Boussinesq case. :math:`\mathrm{Di}`, the +dissipation number, is defined by + +.. math:: + :label: Di + + \mathrm{Di}= \frac{g_o\,\mathrm{L}}{c_\mathrm{P}\,T_o}, + +where :math:`g_o` and :math:`T_o` are the gravitational acceleration +and temperature at the outer boundary respectively. Once more, the +thermal anomaly :math:`\Theta` should be interpreted as (nondimensional) entropy. The symbol :math:`\mathrm{Ra}^*` is the modified Rayleigh number, +given by + +.. math:: + :label: Ra + + \mathrm{Ra}^*=\frac{g_o}{c_\mathrm{P}\Omega_0^2}\frac{\Delta s}{L} + +We thus arrive at the following nondimensionalized equations: + +.. math:: + + \begin{aligned} + \tilde{\rho}(r)\left[\frac{\partial \boldsymbol{v}}{\partial t} + \boldsymbol{v}\cdot\boldsymbol{\nabla}\boldsymbol{v} %advection + + 2\boldsymbol{\hat{z}}\times\boldsymbol{v}\right] =\; % Coriolis + &\mathrm{Ra}^*\tilde{\rho}(r)\left(\frac{r_\mathrm{max}^2}{r^2}\right)\Theta\,\boldsymbol{\hat{r}} % buoyancy + + \tilde{\rho}(r)\boldsymbol{\nabla}\left(\frac{P}{\tilde{\rho}(r)}\right) % pressure + \\ + &+ \frac{\mathrm{E}}{\mathrm{Pm}}\left(\boldsymbol{\nabla}\times\boldsymbol{B}\right)\times\boldsymbol{B} % Lorentz Force + + \mathrm{E}\boldsymbol{\nabla}\cdot\boldsymbol{\mathcal{D}}\\ + % + % + \tilde{\rho}(r)\,\tilde{T}(r)\left[\frac{\partial \Theta}{\partial t} + \boldsymbol{v}\cdot\boldsymbol{\nabla}\Theta + v_r\frac{d\hat{S}}{dr}\right] =\; + &\frac{\mathrm{E}}{\mathrm{Pr}}\boldsymbol{\nabla}\cdot\left[\tilde{\kappa}(r)\tilde{\rho}(r)\,\tilde{T}(r)\,\boldsymbol{\nabla}\Theta \right] % diffusion + + \tilde{Q}(r) % Internal heating + \\ + &+ \frac{\mathrm{E}\,\mathrm{Di}}{\mathrm{Ra}^*}\Phi(r,\theta,\phi) + + \frac{\mathrm{Di\,E^2}}{\mathrm{Pm}^2\mathrm{Ra}^*}\tilde{\eta}(r)|\boldsymbol{\nabla}\times\boldsymbol{B}|^2 \\ % Ohmic Heating + % + % + \frac{\partial \boldsymbol{B}}{\partial t} =\; &\boldsymbol{\nabla}\times\left[\,\boldsymbol{v}\times\boldsymbol{B}-\frac{\mathrm{E}}{\mathrm{Pm}}\tilde{\eta}(r)\boldsymbol{\nabla}\times\boldsymbol{B}\,\right] \\ + % + % + \mathcal{D}_{ij} =\; &2\tilde{\rho}(r)\tilde{\nu}(r)\left[e_{ij} - \frac{1}{3}\boldsymbol{\nabla}\cdot\boldsymbol{v}\right] \\ + % + % + \Phi(r,\theta,\phi) =\; &2\tilde{\rho}(r)\tilde{\nu}(r)\left[e_{ij}e_{ij} - \frac{1}{3}\left(\boldsymbol{\nabla}\cdot\boldsymbol{v}\right)^2\right] \\ + % + % + \boldsymbol{\nabla}\cdot\left[\tilde{\rho}(r)\boldsymbol{v}\right]=\; &0 \\ + \boldsymbol{\nabla}\cdot\boldsymbol{B} =\; &0. \end{aligned} + +.. _notation: + +Notation and Conventions +--------------------------- + +Vector and Tensor Notation +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +All vector quantities are represented in bold italics. Components of a +vector are indicated in non-bold italics, along with a subscript +indicating the direction associated with that component. Unit vectors +are written in lower-case, bold math font and are indicated by the use +of a *hat* character. For example, a vector quantity +:math:`\boldsymbol{a}` would represented as + +.. math:: + :label: vcomp + + \boldsymbol{a} = a_r\boldsymbol{\hat{a}}+a_\theta\boldsymbol{\hat{\theta}}+a_\phi\boldsymbol{\hat{\phi}}. + +The symbols (:math:`\boldsymbol{\hat{r}}`, +:math:`\boldsymbol{\hat{\theta}}`, :math:`\boldsymbol{\hat{\phi}}`) +indicate the unit vectors in the +(:math:`r`,\ :math:`\theta`,\ :math:`\phi`) directions, and +(:math:`a_r`, :math:`a_\theta`, :math:`a_\phi`) indicate the components +of :math:`\boldsymbol{a}` along those directions respectively. + +Vectors may be written in lower case, as with the velocity field +:math:`\boldsymbol{v}`, or in upper case as with the magnetic field +:math:`\boldsymbol{B}`. Tensors are indicated by bold, upper-case, +script font, as with the viscous stress tensor +:math:`\boldsymbol{\mathcal{D}}`. Tensor components are indicated in +non-bold, and with directional subscripts (i.e., +:math:`\mathcal{D}_{r\theta}`). + +Reference-State Values +^^^^^^^^^^^^^^^^^^^^^^ + +The *hat* notation is also used to indicate reference-state quantities. +These quantities are scalar, and they are not written in bold font. They +vary only in radius and have no :math:`\theta`-dependence or +:math:`\phi`-dependence. The reference-state density is indicated by +:math:`\hat{\rho}` and the reference-state temperature by +:math:`\hat{T}`, for instance. + +Averaged and Fluctuating Values +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Most of the output variables have been decomposed into a +zonally-averaged value, and a fluctuation about that average. The +average is indicated by an overbar, such that + +.. math:: + :label: avging + + \overline{a}\equiv \frac{1}{2\pi}\int_{0}^{2\pi} a(r,\theta,\phi)\, \mathrm{d}\phi. + +Fluctations about that average are indicated by a *prime* superscript, +such that + +.. math:: + :label: prime + + a'(r,\theta,\phi)\equiv a(r,\theta,\phi)-\overline{a}(r,\theta) + +Finally, some quantities are averaged over the full sphere. These are +indicated by a double-zero subscript (i.e. :math:`\ell=0,\,m=0`), such +that + +.. math:: + :label: fullsph + + a_{00}\equiv \frac{1}{4\pi}\int_{0}^{2\pi}\int_{0}^{\pi} a(r,\theta,\phi)\, r\mathrm{sin}\,\theta\mathrm{d}\theta\mathrm{d}\phi. + + +.. _streamfunctions: + +The Streamfunction Formulation +------------------------------ + +Section needed. + + +.. _pseudospectral: + +The Psuedospectral Approach +--------------------------- + +Section needed. + +.. _performance: + +Parallelization and Performance +------------------------------- + +Section needed. From 1cd5cb8cda6a45d350dd71b222d08c69c4209c1e Mon Sep 17 00:00:00 2001 From: Nick Nelson Date: Wed, 14 Sep 2022 16:36:42 -0600 Subject: [PATCH 2/5] Updates to run and run at scalle --- doc/source/User_Guide/analyze_output.rst | 175 ++++++++++ doc/source/User_Guide/contribute.rst | 0 doc/source/User_Guide/model_setup.rst | 101 +++++- doc/source/User_Guide/run_at_scale.rst | 36 +++ doc/source/User_Guide/run_rayleigh.rst | 389 +++++++++++++++++++++++ 5 files changed, 698 insertions(+), 3 deletions(-) create mode 100644 doc/source/User_Guide/analyze_output.rst create mode 100644 doc/source/User_Guide/contribute.rst create mode 100644 doc/source/User_Guide/run_at_scale.rst create mode 100644 doc/source/User_Guide/run_rayleigh.rst diff --git a/doc/source/User_Guide/analyze_output.rst b/doc/source/User_Guide/analyze_output.rst new file mode 100644 index 00000000..592ef6e2 --- /dev/null +++ b/doc/source/User_Guide/analyze_output.rst @@ -0,0 +1,175 @@ +Rayleigh comes bundled with an in-situ diagnostics package that allows +the user to sample a simulation in a variety of ways, and at +user-specified intervals throughout a run. This package is comprised of +roughly 17,000 lines of code (about half of the Rayleigh code base), and +it is complex enough that we describe it in two other documents. We +refer the user to : + +#. The diagnostics plotting manual, provided in two formats: + + - Rayleigh/post_processing/Diagnostic_Plotting.ipynb (Jupyter Python + notebook format; recommended for interactive use) + + - Rayleigh/post_processing/Diagnostics_Plotting.html (recommended for optimal + viewing; generated from the .ipynb file) `[html] <../../../post_processing/Diagnostic_Plotting.ipynb>`_ + + +#. :ref:`DValues2` – This companion documentation + provides the output menu system referred to in the main diagnostics + documentation. A number of stand-alone Python plotting examples may also be found in +the Rayleigh/post_processing/ directory. + +The Lookup Table (LUT) +---------------------- + +Rayleigh has on the order of 1,000 possible diagnostic quantities available to the +user. As discussed in the examples above, the user specifies which diagnostic outputs +to compute by providing the appropriate quantity codes in the input file. Internally, +Rayleigh uses the quantity codes similarly to array indices. The purpose of the +lookup table is to map the quantity code to the correct position in the output data +array, you should never assume the quantities will be output in any particular order. +The user may have only requested two quantity codes, for example, 1 and 401. +The output data array will be of size 2 along the axis corresponding to the quantities. +The lookup table could map 401 to the first entry and 1 to the second entry. + +The standard way to interact with the lookup table is to know the quantity code and +explicitly use it. Here we describe an alternative method. Each quantity code entry +(:ref:`quantityCodes`) has an equation, a code, and a name. There are some python +scripts in the post_processing directory that allow you to use the name, instead of +the code, when interacting with the lookup table: + + + lut.py + + generate_mapping.py + + lut_shortcuts.py + +The lut.py file is the main user-interface and contains various utility routines, +including functions to convert between codes and names. The generate_mapping.py file +is responsible for generating the mapping between codes and names. The lut_shortcuts.py +allows users to define their own mapping, allowing a conversion from a user-defined name +to the desired quantity code. The lut_shortcuts.py file does not exist in the source code, +it must be generated by the user; an example shortcuts file can be found in the +post_processing/lut_shortcuts.py.example file. The fastest way to start using shortcuts +is to copy the example file: + +.. code-block:: bash + + cd /path/to/Rayleigh + cd post_processing/ + cp lut_shortcuts.py.example lut_shortcuts.py + +and then make edits to the new lut_shortcuts.py file. + +The mapping has already been generated and is stored in the lut_mapping.py file. For +developers or anyone wanting to re-generate the mapping, use the generate_mapping.py file: + +.. code-block:: bash + + python generate_mapping.py /path/to/Rayleigh + +This will parse the Rayleigh directory tree and generate the standard mapping between +quantity codes and their associated names stored in the new file lut_mapping.py. Only +quantity codes that are defined within the Rayleigh source tree will be included. +Rayleigh does not need to be compiled before generating the mapping. + +If a user has a custom directory where output diagnostics are defined, the above command +will not capture the custom diagnostic codes. To include custom quantities, the user +must generate the mapping themselvese with the generate_mapping.py file: + +.. code-block:: bash + + python generate_mapping.py /path/to/Rayleigh/ --custom-dir=/path/to/custom/ + +Note that the Rayleigh directories are identical between the two calls, the only addition +is the custom-dir flag. This command will generate a new mapping stored in the file +lut_mapping_custom.py and will include all of the standard output quantities as well as +the custom diagnostics. + +Without using this mapping technique, plotting something like the kinetic energy could +appear as: + +.. code-block:: python + + from rayleigh_diagnostics import G_Avgs, build_file_list + + files = build_file_list(0, 10000000, path='G_Avgs') + g = G_Avgs(filename=files[0], path='') + + ke_code = g.lut[401] # must use quantity code in lookup table + + ke = g.data[:, ke_code] # extract KE as a function of time + +With the newly generated mapping, the above code could be rewritten as: + +.. code-block:: python + + from rayleigh_diagnostics import G_Avgs, build_file_list + + from lut import lookup # <-- import helper function from main interface + + files = build_file_list(0, 10000000, path='G_Avgs') + g = G_Avgs(filename=files[0], path='') + + ke_code = g.lut[lookup('kinetic_energy')] # use quantity *name* in lookup table + + ke = g.data[:, ke_code] # extract KE as a function of time, same as before + +There is one drawback to using the quantity names: the naming scheme is somewhat +random and they can be quite long strings. This is where the lut_shortcuts.py +can be very useful. This allows users to define their own names to use in the mapping. +These are defined in the lut_shortcuts.py file and always take the form: + +.. code-block:: python + + shortcuts['custom_name'] = 'rayleigh_name' + +where custom_name is defined by the user, and rayleigh_name is the quantity name that +Rayleigh uses. The main dictionary must be named 'shortcuts'. With an entry like: + +.. code-block:: python + + shortcuts['ke'] = 'kinetic_energy' + +the above example for extracting the kinetic energy is even more simple: + +.. code-block:: python + + from rayleigh_diagnostics import G_Avgs, build_file_list + + from lut import lookup # <-- import helper function from main interface + + files = build_file_list(0, 10000000, path='G_Avgs') + g = G_Avgs(filename=files[0], path='') + + ke_code = g.lut[lookup('ke')] # user defined *name* in lookup table + + ke = g.data[:, ke_code] # extract KE as a function of time, same as before + +.. _post_scripts: + +Plotting Examples +----------------- + +.. note:: + + Please note this notebook has not been updated since the conversion to online documentation (July 2019). + The Rayleigh/doc directory has been reorganized. A pdf version of the document + can be created by the user through the website. + +.. toctree:: + :titlesonly: + + ../../../post_processing/Diagnostic_Plotting.ipynb + +.. _viz_3d: + +3-D Visualization with VAPOR +---------------------------- + +Need text here. + +.. _commmon_diagnostics: + +Common Diagnostics +------------------ + + diff --git a/doc/source/User_Guide/contribute.rst b/doc/source/User_Guide/contribute.rst new file mode 100644 index 00000000..e69de29b diff --git a/doc/source/User_Guide/model_setup.rst b/doc/source/User_Guide/model_setup.rst index 97b2d805..064bcb94 100644 --- a/doc/source/User_Guide/model_setup.rst +++ b/doc/source/User_Guide/model_setup.rst @@ -600,10 +600,105 @@ Need text here. .. _surveys: -Setting Up a Survey -------------------- +Ensemble Mode +------------- + +Rayleigh can also be used to run multiple simulations under the umbrella +of a single executable. This functionality is particularly useful for +running parameter space studies, which often consist of mulitple, +similarly-sized simulations, in one shot. Moreover, as some queuing +systems favor large jobs over small jobs, an ensemble mode is useful for +advancing multiple small simulations through the queue in a reasonable +timeframe. + +Running Rayleigh in ensemble mode is relatively straightforward. To +begin with, create a directory for each simulation as you normally +would, and place an appropriately modified main_input into each +directory. These directories should all reside within the same parent +directory. Within that parent directory, you should place a copy of the +Rayleigh executable (or a softlink). In addition, you should create a +text file named **run_list** that contains the name of each simulation +directory, one name per line. An ensemble job may then be executed by +calling Rayleigh with **nruns** command line flag as: -Need text here. +:: + + user@machinename ~/runs/ $ mpiexec -np Y ./rayleigh.opt -nruns X + +Here, Y is the total number of cores needed by all X simulations listed +in run_list. + +**Example:** Suppose you wish to run three simulations at once from +within a parent directory named *ensemble* and that the simulation +directories are named run1, run2, and run3. When performing an *ls* from +within *ensemble*, you should see 5 items. + +:: + + user@machinename ~/runs/ $ cd ensemble + user@machinename ~/runs/ensemble $ ls + rayleigh.opt run1 run2 run3 run_list + +In this example, the contents of run_list should be the *local* names of +your ensemble run-directories, namely run1, run2, and run3. + +:: + + user@machinename ~runs/ensemble $ more run_list + run1 + run2 + run3 + <-- place an empty line here + +Note that some Fortran implementations will not read the last line in +run_list unless it ends in a newline character. Avoid unexpected crashes +by hitting "enter" following your final entry in run_list. + +Before running Rayleigh, make sure you know how many cores each +simulation needs by examining the main_input files: + +:: + + user@machinename ~runs/ensemble $ head run1/main_input + &problemsize_namelist + n_r = 128 + n_theta = 192 + nprow = 16 + npcol = 16 + / + + user@machinename ~runs/ensemble $ head run2/main_input + &problemsize_namelist + n_r = 128 + n_theta = 384 + nprow = 32 + npcol = 16 + / + + user@machinename ~runs/ensemble $ head run3/main_input + &problemsize_namelist + n_r = 64 + n_theta = 192 + nprow = 16 + npcol = 16 + / + +In this example, we need a total of 1024 cores (256+512+256) to execute +three simulations, and so the relevant call to Rayleigh would be: + +:: + + user@machinename ~/runs/ $ mpiexec -np 1024 ./rayleigh.opt -nruns 3 +**Closing Notes:** When running in ensemble mode, it is *strongly +recommended* that you redirect standard output for each simulation to a +text file (see §\ :ref:`io`). Otherwise, all simulations +write to the same default (machine-dependent) log file, making it +difficult to read. Moreover, some machines such as NASA Pleiades will +terminate a run if the log file becomes too long. This is easy to do +when multiple simulations are writing to the same file. +Finally, The flags -nprow and -npcol **are ignored** when -nruns is +specified. The row and column configuration for all simulations needs to +be specified in their respective main_input files instead. diff --git a/doc/source/User_Guide/run_at_scale.rst b/doc/source/User_Guide/run_at_scale.rst new file mode 100644 index 00000000..e8952f63 --- /dev/null +++ b/doc/source/User_Guide/run_at_scale.rst @@ -0,0 +1,36 @@ +.. raw:: latex + + \clearpage + +.. _run_scale: + +Running at Scale +================ + +.. _get_ready: + +Getting Ready for Large Runs +---------------------------- + +Need text here. + +.. _modules_queues: + +Modules and Queues +------------------ + +Need text here. + +.. _example_modules: + +Example Configurations +---------------------- + +Need text here. + +.. _jobscripts: + +Sample Jobscripts +----------------- + +Need text here. \ No newline at end of file diff --git a/doc/source/User_Guide/run_rayleigh.rst b/doc/source/User_Guide/run_rayleigh.rst new file mode 100644 index 00000000..78ee6753 --- /dev/null +++ b/doc/source/User_Guide/run_rayleigh.rst @@ -0,0 +1,389 @@ +.. raw:: latex + + \clearpage + +.. _run_rayleigh: + +Running Rayleigh +================ + +After setting up a custom `main_input` file, now it is time to run the new model. +This section focuses on the basics of running a Rayleigh model. + +.. _load_balance: + +Load-Balancing +--------------------------------- + +Rayleigh is parallelized using MPI and a 2-D domain decomposition. The +2-D domain decomposition means that we envision the MPI Ranks as being +distributed in rows and columns. The number of MPI ranks within a row is +*nprow* and the number of MPI ranks within a column is *npcol*. When +Rayleigh is run with N MPI ranks, the following constraint must be +satisfied: + +.. math:: \mathrm{N} = \mathrm{npcol} \times \mathrm{nprow} . + +If this constraint is not satisfied , the code will print an error +message and exit. The values of *nprow* and *npcol* can be specified in +*main_input* or on the command line via the syntax: + +:: + + mpiexec -np 8 ./rayleigh.opt -nprow 4 -npcol 2 + + +Rayleigh’s performance is sensitive to the values of *nprow* and +*npcol*, as well as the number of radial grid points :math:`N_r` and +latitudinal grid points :math:`N_\theta`. If you examine the main_input +file, you will see that it is divided into Fortran namelists. The first +namelist is the problemsize_namelist. Within this namelist, you will see +a place to specify nprow and npcol. Edit main_input so that nprow and +npcol agree with the N you intend to use (or use the command-line syntax +mentioned above). The dominate effect on parallel scalability is the +number of messages sent per iteration. For optimal message counts, nprow +and npcol should be as close to one another in value as possible. + +#. N = nprow :math:`\times` npcol. + +#. nprow and npcol should be equal or within a factor of two of one + another. + +The value of nprow determines how spherical harmonics are distributed +across processors. Spherical harmonics are distributed in +high-\ :math:`m`/low-:math:`m` pairs, where :math:`m` is the azimuthal +wavenumber. Each process is responsible for all :math:`\ell`-values +associated with those :math:`m`\ ’s contained in memory. + +The value of npcol determines how radial levels are distributed across +processors. Radii are distributed uniformly across processes in +contiguous chunks. Each process is responsible for a range of radii +:math:`\Delta r`. + +The number of spherical harmonic degrees :math:`N_\ell` is defined by + +.. math:: N_\ell = \frac{2}{3}N_\theta + +For optimal load-balancing, *nprow* should divide evenly into +:math:`N_r` and *npcol* should divide evenly into the number of +high-\ :math:`m`/low-:math:`m` pairs (i.e., :math:`N_\ell/2`). Both +*nprow* and *npcol* must be at least 2. + +In summary, + +#. :math:`nprow \ge 2`. + +#. :math:`npcol \ge 2`. + +#. :math:`n \times npcol = N_r` (for integer :math:`n`). + +#. :math:`k \times nprow = \frac{1}{3}N_\theta` (for integer :math:`k`). + + +.. _checkpointing: + +Checkpointing +------------- + +We refer to saved states in Rayleigh as **checkpoints**. A single +checkpoint consists of 13 files when magnetism is activated, and 9 files +when magnetism is turned off. A checkpoint written at time step *X* +contains all information needed to advance the system to time step +*X+1*. Checkpoint filenames end with a suffix indicating the contents of +the file (see Table table_checkpoints_). Each +checkpoint filename possess a prefix as well. Files belonging to the +same checkpoint share the same prefix. A checkpoint file collection, +written at time step 10,000 would look like that shown in Table +table_checkpoints_. + + .. _table_checkpoints: + +.. centered:: **Table. Checkpoints.** + +Example checkpoint file collection for a +time step 10,000. File contents are indicated. + + +-----------------------------------+-----------------------------------+ + | Filename | Contents | + +===================================+===================================+ + | 00010000_W | Poloidal Stream function (at time | + | | step 10,000) | + +-----------------------------------+-----------------------------------+ + | 00010000_Z | Toroidal Stream function | + +-----------------------------------+-----------------------------------+ + | 00010000_P | Pressure | + +-----------------------------------+-----------------------------------+ + | 00010000_S | Entropy | + +-----------------------------------+-----------------------------------+ + | 00010000_C | Poloidal Vector Potential | + +-----------------------------------+-----------------------------------+ + | 00010000_A | Toroidal Vector Potential | + +-----------------------------------+-----------------------------------+ + | 00010000_WAB | Adams-Bashforth (A-B) terms for | + | | radial momentum (W) equation | + +-----------------------------------+-----------------------------------+ + | 00010000_ZAB | A-B terms for radial vorticity | + | | (Z) equation | + +-----------------------------------+-----------------------------------+ + | 00010000_PAB | A-B terms for horizontal | + | | divergence of momentum (dWdr) | + | | equation | + +-----------------------------------+-----------------------------------+ + | 00010000_SAB | A-B terms for Entropy equation | + +-----------------------------------+-----------------------------------+ + | 00010000_CAB | A-B terms for C-equation | + +-----------------------------------+-----------------------------------+ + | 00010000_AAB | A-B terms for A-equation | + +-----------------------------------+-----------------------------------+ + | 00010000_grid_etc | grid and time-stepping info | + +-----------------------------------+-----------------------------------+ + +These files contain all information needed to advance the system state +from time step 10,000 to time step 10,001. Checkpoints come in two +flavors, denoted by two different prefix conventions: **standard +checkpoints** and **quicksaves**. This section discusses how to generate +and restart from both types of checkpoints. + +Standard Checkpoints +~~~~~~~~~~~~~~~~~~~ + +Standard checkpoints are intended to serve as regularly spaced restart +points for a given run. These files begin with an 8-digit prefix +indicating the time step at which the checkpoint was created. + +The frequency with which standard checkpoints are generated can be +controlled by modifying the **checkpoint_interval** variable in the +**temporal_controls_namelist**. For example, if you want to generate a +checkpoint once every 50,000 time steps, you would modify your +main_input file to read: + +:: + + &temporal_controls_namelist + checkpoint_interval = 50000 ! Checkpoint every 50,000 time steps + / + +The default value of checkpoint_interval is 1,000,000, which is +typically much larger than what you will use in practice. + +Restarting from a checkpoint is accomplished by first assigning a value +of -1 to the variables **init_type** and/or **magnetic_init_type** in +the **initial_conditions_namelist**. In addition, the time step from +which you wish to restart from should be specified using the +**restart_iter** variable in the initial_conditions_namelist. The +example below will restart both the magnetic and hydrodynamic variables +using the set of checkpoint files beginning with the prefix 00005000. + +:: + + &initial_conditions_namelist + init_type = -1 !Restart magnetic and hydro variables from time step 5,000 + magnetic_init_type = -1 + restart_iter = 5000 + / + +When both values are set to -1, hydrodynamic and magnetic variables are +read from the relevant checkpoint files. Alternatively, magnetic and +hydrodynamic variables may be initialized separately. This allows you to +add magnetism to an already equilibrated hydrodynamic case, for +instance. The example below will initialize the system with a random +magnetic field, but it will read the hydrodynamic information (W,Z,S,P) +from a checkpoint created at time step 5,000: + +:: + + &initial_conditions_namelist + init_type = -1 ! Restart hydro from time step 5,000 + magnetic_init_type = 7 ! Add a random magnetic field + restart_iter = 5000 + / + +In addition to specifying the checkpoint time step manually, you can +tell Rayleigh to simply restart using the last checkpoint written by +assigning a value of zero to restart_iter: + +:: + + &initial_conditions_namelist + init_type = -1 + magnetic_init_type = 7 + restart_iter = 0 ! Restart using the most recent checkpoint + / + +In this case, Rayleigh reads the **last_checkpoint** file (found within +the Checkpoints directory) to determine which checkpoint it reads. + +.. _quicksaves: + +Quicksaves +~~~~~~~~~~ + +In practice, Rayleigh checkpoints are used for two purposes: (1) +guarding against unexpected crashes and (2) supplementing a run’s record +with a series of restart points. While standard checkpoints may serve +both purposes, the frequency with which checkpoints are written for +purpose (1) is often much higher than that needed for purpose (2). This +means that a lot of data culling is performed at the end of a run or, if +disk space is a particularly limiting factor, during the run itself. For +this reason, Rayleigh has a **quicksave** checkpointing scheme in +addition to the standard scheme. Quicksaves can be written with +high-cadence, but require low storage due to the rotating reuse of +quicksave files. + +The cadence with which quicksaves are written can be specified by +setting the **quicksave_interval** variable in the +**temporal_controls_namelist**. Alternatively, the elapsed wall time (in +minutes) that passes between quicksaves may be controlled by specifying +the **quicksave_minutes** variable. If both quicksave_interval and +quicksave_minutes are specified, quicksave_minutes takes precedence. + +What distinguishes quicksaves from standard checkpoints is that only a +specified number of quicksaves exist on the disk at any given time. That +number is determined by the value of **num_quicksaves**. Quicksave files +begin with the prefix *quicksave_XX*, where XX is a 2-digit code, +ranging from 1 through num_quicksaves and indicates the quicksave +number. Consider the following example: + +:: + + &temporal_controls_namelist + checkpoint_interval = 35000 ! Generate a standard checkpoint once every 35,000 time steps + quicksave_interval = 10000 ! Generate a quicksave once every 10,000 time steps + num_quicksaves = 2 ! Keep only two quicksaves on disk at a time + / + +At time step 10,000, a set of checkpoint files beginning with prefix +quicksave_01 will be generated. At time step 20,000, a set of checkpoint +files beginning with prefix quicksave_02 will be generated. Following +that, at time step 30,000, another checkpoint will be generated, *but it +will overwrite the existing quicksave_01 files*. At time step 40,000, +the quicksave_02 files will be overwritten, and so forth. Because the +**num_quicksaves** was set to 2, filenames with prefix quicksave_03 will +never be generated. + +Note that checkpoints beginning with an 8-digit prefix (e.g., 00035000) +are still written to disk regularly and are not affected by the +quicksave checkpointing. On time steps where a quicksave and a standard +checkpoint would both be written, only the standard checkpoint is +written. Thus, at time step 70,000 in the example above, a standard +checkpoint would be written, and the files beginning with quicksave_01 +would remain unaltered. + +Restarting from quicksave_XX may be accomplished by specifying the value +of restart_iter to be -XX (i.e., the negative of the quicksave you wish +to restart from). The following example shows how to restart the +hydrodynamic variables from quicksave_02, while also initializing a +random magnetic field. + +:: + + &initial_conditions_namelist + init_type = -1 ! Restart hydro variables from a checkpoint + magnetic_init_type = 7 ! Initialize a random magnetic field + restart_iter = -2 ! Restart from quicksave number 2 + / + +Note that the file last_checkpoint contains the number of last +checkpoint written. This might be a quicksave or a standard checkpoint. +Specifying a value of zero for restart_iter thus works with quicksaves +and standard checkpoints alike. + +Checkpoint Logs +~~~~~~~~~~~~~~~ + +When checkpoints are written, the number of the most recent checkpoint +is appended to a file named **checkpoint_log**, found in the Checkpoints +directory. The checkpoint log can be used to identify the time step +number of a quicksave file that otherwise has no identifying +information. While this information is also contained in the grid_etc +file, those are written in unformatted binary and cumbersome to access +from the terminal command line. + +An entry in the log of "00050000 02" means that a checkpoint was written +at time step 50,000 to quicksave_02. An entry lacking a two-digit number +indicates that a standard checkpoint was written at that time step. The +most recent entry in the checkpoint log always comes at the end of the +file. + +.. _control_time: + +Controlling Run Length & Time Stepping +-------------------------------------- + +A simulation’s runtime and time-step size can be controlled using the +**temporal_controls** namelist. The length of time for which a +simulation runs before completing is controlled by the namelist variable +**max_time_minutes**. The maximum number of time steps that a simulation +will run for is determined by the value of the namelist +**max_iterations**. The simulation will complete when it has run for +*max_time_minutes minutes* or when it has run for *max_iterations time +steps* – whichever occurs first. + +An orderly shutdown of Rayleigh can be manually triggered by creating a file +with the name set in **terminate_file** (i.e., running the command *touch +terminate* in the default setting). If the file is found, Rayleigh will stop +after the next time step and write a checkpoint file. The existence of +**terminate_file** is checked every **terminate_check_interval** iterations. +The check can be switched off completely by setting +**terminate_check_interval** to -1. Both of these options are set in the +**io_controls_namelist**. With the appropriate job script this feature can be +used to easily restart the code with new settings without losing the current +allocation in the queuing system. A **terminate_file** left over from +a previous run is automatically deleted when the code starts. + +Time-step size in Rayleigh is controlled by the Courant-Friedrichs-Lewy +condition (CFL; as determined by the fluid velocity and Alfvén speed). A +safety factor of **cflmax** is applied to the maximum time step +determined by the CFL. Time-stepping is adaptive. An additional variable +**cflmin** is used to determine if the time step should be increased. + +The user may also specify the maximum allowed time-step size through the +namelist variable **max_time_step**. The minimum allowable time-step +size is controlled through the variable **min_time_step**. If the CFL +condition is less than this value, the simulation will exit. + +Let :math:`\Delta t` be the current time-step size, and let +:math:`t_\mathrm{CFL}` be the maximum time-step size as determined by +the CFL limit. The following logic is employed by Rayleigh when +calculating the time-step size: + +- IF { :math:`\Delta_t\ge \mathrm{cflmax}\times t_\mathrm{CFL}` } THEN + { :math:`\Delta_t` is set to + :math:`\mathrm{cflmax}\times t_\mathrm{CFL}` }. + +- IF { :math:`\Delta_t\le \mathrm{cflmin}\times t_\mathrm{CFL}` } THEN + { :math:`\Delta_t` is set to + :math:`\mathrm{cflmax}\times t_\mathrm{CFL}` }. + +- IF{ :math:`t_\mathrm {CFL}\ge \mathrm{max\_time\_step}` } THEN { + :math:`\Delta_t` is set to max_time_step } + +- IF{ :math:`t_\mathrm {CFL}\le \mathrm{min\_time\_step}` } THEN { + Rayleigh Exits } + +The default values for these variables are: + +:: + + &temporal_controls_namelist + max_iterations = 1000000 + max_time_minutes = 1d8 + cflmax = 0.6d0 + cflmin = 0.4d0 + max_time_step = 1.0d0 + min_time_step = 1.0d-13 + / + +.. _log_file: + +The Log File +------------ + +Section needs to be written. + +.. _run_termination: + +Run Termination +--------------- + +Section needs to be written. From a85c4ad85d42d1b936cbd48bdb75ec6da030f349 Mon Sep 17 00:00:00 2001 From: Nick Nelson Date: Thu, 15 Sep 2022 09:27:14 -0600 Subject: [PATCH 3/5] Continued Updates Updates to contribute.rst and model_setup.rst --- doc/source/User_Guide/contribute.rst | 6 ++ doc/source/User_Guide/index.rst | 11 ++- doc/source/User_Guide/model_setup.rst | 110 +++++++++++++++++++++++++- 3 files changed, 125 insertions(+), 2 deletions(-) diff --git a/doc/source/User_Guide/contribute.rst b/doc/source/User_Guide/contribute.rst index e69de29b..57bc3af7 100644 --- a/doc/source/User_Guide/contribute.rst +++ b/doc/source/User_Guide/contribute.rst @@ -0,0 +1,6 @@ +.. _contribute: + +Contributing to Rayleigh +======================== + +Need text here. \ No newline at end of file diff --git a/doc/source/User_Guide/index.rst b/doc/source/User_Guide/index.rst index a443887c..c51b3b44 100644 --- a/doc/source/User_Guide/index.rst +++ b/doc/source/User_Guide/index.rst @@ -1,10 +1,19 @@ -User Guide +User Manual ******************** .. toctree:: :maxdepth: 2 :caption: Contents: + getting_started + physics_math_overview + model_setup + run_rayleigh + run_at_scale + analyze_output + contribute + + overview installation devel_environment running diff --git a/doc/source/User_Guide/model_setup.rst b/doc/source/User_Guide/model_setup.rst index 064bcb94..5b73ef7a 100644 --- a/doc/source/User_Guide/model_setup.rst +++ b/doc/source/User_Guide/model_setup.rst @@ -596,7 +596,115 @@ Files output in this way will have the filename of their iteration. Exampels from Recent Publications --------------------------------- -Need text here. +*A Solar-like Case* + +This is the main_input file from Case 39 from: + +`Hindman, Bradley W., Nicholas A. Featherstone, and Keith Julien. 2020. “Morphological +Classification of the Convective Regimes in Rotating Stars.” The Astrophysical Journal +898 (2): 120. https://doi.org/10.3847/1538-4357/ab9ec2.` + + + +:: + &problemsize_namelist + n_r = 64 + n_theta = 192 + nprow = 32 + npcol = 32 + rmin = 5.0d10 + rmax = 6.5860209d10 + / + &numerical_controls_namelist + / + &physical_controls_namelist + rotation = .true. + magnetism = .false. + / + &temporal_controls_namelist + max_time_step = 1000.0d0 + max_iterations = 5000000 + checkpoint_interval = 50000 + quicksave_interval = 10000 + num_quicksaves = 4 + cflmin = 0.4d0 + cflmax = 0.6d0 + / + &io_controls_namelist + / + &output_namelist + !shellslice_levels = 16,32,48,64,80,96,112 + !shellslice_values = 1 ! Codes needed for standard output routines + shellslice_levels = 8,16,24,32,40,48,56,64,72,80,88,96,104,112,120 + shellslice_values = 1,2,3,301,302,303,304,305,306,307,308,309,401,501,502,2701,2702,2703,2704,2705,2706,2707,2708,2709,2710,2711 + shellslice_frequency = 10000 + shellslice_nrec = 1 + + !shellspectra_values = 1,2,3 ! Codes needed for standard output routines + shellspectra_levels = 16,32,48,64,80,96,112 + shellspectra_values = 1,2,3,301,302,303,304,305,306,307,308,309,401,501,502,503,504,2701,2702,2703,2704,2705,2706,2707,2708,2709,2710,2711 + shellspectra_frequency = 10000 + shellspectra_nrec = 1 + + !azavg_values = 1,2,3,201,202 ! Codes needed for standard output routines + azavg_values = 1,2,3,201,202,401,405,409,501,502,1433,1455,1470,1923,1935,1943,2701,2702,2703,2704,2705,2706,2707,2708,2709,2710,2711,2712,2713,2714,2715 + azavg_frequency = 1000 + azavg_nrec = 10 + + !shellavg_values = 1,2,3,501,502,1433,1455,1470,1923,1935 ! Codes needed for standard output routines + shellavg_values = 1,2,3,401,405,409,501,502,1433,1455,1470,1923,1935,2701,2702,2703,2704,2705,2706,2707,2708,2709,2710,2711,2712,2713,2714,2715 + shellavg_frequency = 100 + shellavg_nrec = 100 + + !globalavg_values = 401,402,403,404,405,406,407,408,409,410,411,412 ! Codes needed for standard output routines + globalavg_values = 401,402,403,404,405,406,407,408,409,410,411,412,413,417,421,2701,2702,2703,2704,2705,2706,2707 + globalavg_frequency = 100 + globalavg_nrec = 100 + + !equatorial_values = 1,3 ! Codes needed for standard output routines + equatorial_values = 1,2,3,4,5,6,201,203,301,302,303,304,305,306,307,308,309,401,501,502,503,504,2701,2702,2703,2704,2705,2706,2707,2708,2709,2710,2711 + equatorial_frequency = 10000 + equatorial_nrec = 1 + + full3d_values = 4 + full3d_frequency = 9000000 + / + + &Boundary_Conditions_Namelist + no_slip_boundaries = .false. + strict_L_Conservation = .false. + dtdr_bottom = 0.0d0 + T_Top = 0.0d0 + T_Bottom = 851225.7d0 + fix_tvar_top = .true. + fix_tvar_bottom = .false. + fix_dtdr_bottom = .true. + / + &Initial_Conditions_Namelist + init_type = 7 + magnetic_init_type = -1 + mag_amp = 1.0d0 + temp_amp = 1.0d1 + temp_w = 0.01d4 + !restart_iter = 0 ! restart from latest checkpoint of any flavor + / + &Test_Namelist + / + &Reference_Namelist + reference_type = 2 + heating_type = 1 + luminosity = 3.846d33 + poly_n = 1.5d0 + poly_Nrho = 3.0d0 + poly_mass = 1.98891D33 + poly_rho_i = 0.18053428d0 + pressure_specific_heat = 3.5d8 + angular_velocity = 5.74d-6 ! Sidereal period of 12.7 days (twice the sidereal Carrington rate) + / + &Transport_Namelist + nu_top = 4.d12 + kappa_top = 4.d12 + / .. _surveys: From b641f7c98def9b9c0e2e63292bfb72f43f1fe7c4 Mon Sep 17 00:00:00 2001 From: Nick Nelson Date: Thu, 15 Sep 2022 10:26:32 -0600 Subject: [PATCH 4/5] Added troubleshooting section. --- .gitignore | 1 + doc/source/User_Guide/index.rst | 1 + doc/source/User_Guide/troubleshooting.rst | 36 +++++++++++++++++++++++ 3 files changed, 38 insertions(+) create mode 100644 doc/source/User_Guide/troubleshooting.rst diff --git a/.gitignore b/.gitignore index 8fa1d476..ca5bda8f 100755 --- a/.gitignore +++ b/.gitignore @@ -89,3 +89,4 @@ dimensional.dat Boussinesq.dat custom_ref_viscous.dat cref_from_MESA.dat +.vscode/settings.json diff --git a/doc/source/User_Guide/index.rst b/doc/source/User_Guide/index.rst index c51b3b44..c23f1373 100644 --- a/doc/source/User_Guide/index.rst +++ b/doc/source/User_Guide/index.rst @@ -12,6 +12,7 @@ User Manual run_at_scale analyze_output contribute + troubleshooting overview installation diff --git a/doc/source/User_Guide/troubleshooting.rst b/doc/source/User_Guide/troubleshooting.rst new file mode 100644 index 00000000..fac67696 --- /dev/null +++ b/doc/source/User_Guide/troubleshooting.rst @@ -0,0 +1,36 @@ +.. raw:: latex + + \clearpage + +.. _troubleshooting: + +Troubleshooting +=============== + +.. _compile_error: + +Compiling Errors +---------------- + +Need text here. + +.. _seg_fault: + +Segmentation Fault Crashes +-------------------------- + +Need test here. + +.. _timestep_crash: + +Timestep Crashes +---------------- + +Need text here. + +.. _ringing: + +Numerical Ringing +----------------- + +Need text here. \ No newline at end of file From 08132651d1ac054c1807c58d10501e21751753eb Mon Sep 17 00:00:00 2001 From: Nick Nelson Date: Thu, 15 Sep 2022 10:30:15 -0600 Subject: [PATCH 5/5] Update index.rst --- doc/source/User_Guide/index.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/source/User_Guide/index.rst b/doc/source/User_Guide/index.rst index c23f1373..cbc81231 100644 --- a/doc/source/User_Guide/index.rst +++ b/doc/source/User_Guide/index.rst @@ -5,6 +5,9 @@ User Manual :maxdepth: 2 :caption: Contents: + .. + New User Guide + getting_started physics_math_overview model_setup @@ -14,6 +17,10 @@ User Manual contribute troubleshooting + .. + Old User Manual + + overview installation devel_environment