From f388117bd3e6a5baa4a5badc9e5f242c68e1ef45 Mon Sep 17 00:00:00 2001 From: Jez Swann Date: Tue, 24 Sep 2024 14:21:48 +0100 Subject: [PATCH] Final broad docs structure changes and tidying ready for work packages. --- doc/source/user_guide/boundary_conditions.rst | 85 ++- doc/source/user_guide/case.rst | 550 +----------------- doc/source/user_guide/installing.rst | 15 +- doc/source/user_guide/intro.rst | 2 +- doc/source/user_guide/meshing.rst | 6 +- doc/source/user_guide/postprocessing.rst | 36 +- doc/source/user_guide/running.rst | 2 +- 7 files changed, 100 insertions(+), 596 deletions(-) diff --git a/doc/source/user_guide/boundary_conditions.rst b/doc/source/user_guide/boundary_conditions.rst index 520a6b17f..f5609e962 100644 --- a/doc/source/user_guide/boundary_conditions.rst +++ b/doc/source/user_guide/boundary_conditions.rst @@ -16,35 +16,76 @@ nekRS, ``parHelp.txt`` and below. .. literalinclude:: ../../parHelp.txt :language: none - :lines: 1-3, 144-166 + :lines: 1-3, 149-179 +.. tip:: -User Defined Value/Gradient -""""""""""""""""""""""""""" - -boundary codedfixedvalue codedfixedgradient - -name gets suffixed mesh, velocity, fixed or scalar - -interface is bcData struct - -bcData struct mention or table -nx - normal - -t1x + To setup some cases, you may need to use the ``boundaryIDMap`` parameter of + the ``MESH`` section to apply the ``boundaryTypeMap`` options to the correct + boundary IDs of the mesh (By default NekRS assumes that the boundaryIDs start + at 1). Below is an example where the four boundary conditions are + applied to the boundary IDs 389 (``codeFixedValue``), 231 (``zeroGradient``), + 4 (``zeroValue``) and 23 (``zeroValue``). -u - velocity + .. code-block:: + [VELOCITY] + boundaryTypeMap = codedFixedValue, zeroGradient, zeroValue, zeroValue -For each of the values that have a function name present, this must be created -within the ``.udf`` file when used (E.G. setting a ``codedFixedValue`` boundary will -require the ``velocityDirichletConditions`` to be present in the OKL section). + [MESH] + boundaryIDMap = 389, 231, 4, 23 -.. tip:: +User Defined Value/Gradient +""""""""""""""""""""""""""" - To setup some cases (E.G. periodic boundary conditions), you may need to use the - ``boundaryIDMap`` parameter of the ``MESH`` section to apply the ``boundaryTypeMap`` - options to the correct boundary IDs (NekRS assumed that the boundaryIDs start at 1). +If a boundary condition requires a value setting rather than just a type, a +suitable function will need to be provided within the ``.udf`` file. The name of +the function used should be in the form of ``codedFixed`` + ``Value/Gradient`` ++ ``Velocity/Scalar/Mesh``, E.G. ``codedFixedValueVelocity``, +``codedFixedGradientScalar`` and ``codedFixedValueMesh``. + +All of these functions are passed the ``bcData`` struct which has the following +parameters available: + ++-----------------------------------------------------+------------------------------+------------------------------+ +| Name | Type | Description | ++=====================================================+==============================+==============================+ +| ``idM`` | ``int`` | | ++-----------------------------------------------------+------------------------------+------------------------------+ +| ``fieldOffset`` | ``int`` | | ++-----------------------------------------------------+------------------------------+------------------------------+ +| ``id`` | ``int`` | | ++-----------------------------------------------------+------------------------------+------------------------------+ +| ``time`` | ``double`` | | ++-----------------------------------------------------+------------------------------+------------------------------+ +| ``x``, ``y``, ``z`` | ``dfloat`` | | ++-----------------------------------------------------+------------------------------+------------------------------+ +| ``nx``, ``ny``, ``nz`` | ``dfloat`` | normals | ++-----------------------------------------------------+------------------------------+------------------------------+ +| ``1x``, ``t1y``, ``t1z``, ``t2x``, ``t2y``, ``t2z`` | ``dfloat`` | tangential directions | ++-----------------------------------------------------+------------------------------+------------------------------+ +| ``tr1``, ``tr2`` | ``dfloat`` | | ++-----------------------------------------------------+------------------------------+------------------------------+ +| ``u``, ``v``, ``w`` | ``dfloat`` | velocity | ++-----------------------------------------------------+------------------------------+------------------------------+ +| ``p`` | ``dfloat`` | | ++-----------------------------------------------------+------------------------------+------------------------------+ +| ``uinterp``, ``vinterp``, ``winterp`` | ``dfloat`` | interpolated velocity values | ++-----------------------------------------------------+------------------------------+------------------------------+ +| ``scalarId`` | ``int`` | | ++-----------------------------------------------------+------------------------------+------------------------------+ +| ``s`` | ``dfloat`` | | ++-----------------------------------------------------+------------------------------+------------------------------+ +| ``flux`` | ``dfloat`` | | ++-----------------------------------------------------+------------------------------+------------------------------+ +| ``sinterp`` | ``dfloat`` | interpolated scalar value | ++-----------------------------------------------------+------------------------------+------------------------------+ +| ``meshu``, ``meshv``, ``meshw`` | ``dfloat`` | | ++-----------------------------------------------------+------------------------------+------------------------------+ +| ``trans``, ``diff`` | ``dfloat`` | properties | ++-----------------------------------------------------+------------------------------+------------------------------+ +| ``usrwrk`` | ``@globalPtr const dfloat*`` | | ++-----------------------------------------------------+------------------------------+------------------------------+ Internal / Periodic """"""""""""""""""" diff --git a/doc/source/user_guide/case.rst b/doc/source/user_guide/case.rst index d5d87b64d..daec2b10f 100644 --- a/doc/source/user_guide/case.rst +++ b/doc/source/user_guide/case.rst @@ -80,26 +80,9 @@ The valid sections for setting up a nekRS simulation are: * ``VELOCITY``: settings for the velocity solution * ``CASEDATA``: custom settings -Each of the keys and value types are now described for these sections. The -formatting used here to describe valid key, value combinations is as follows. -Take the ``backend`` key in the ``OCCA`` section as an example: - -**backend** *(CUDA), CPU, HIP, OPENCL, OPENMP, SERIAL* [``THREAD MODEL``] - -Here, ``backend`` is the key, and ``CUDA``, ``CPU``, ``HIP``, ``OPENCL``, ``OPENMP``, -and ``SERIAL`` are all valid values. Defaults are indicated in parentheses - therefore, -if you do not explicitly give the ``backend`` in the ``.par`` file, -the :term:`CUDA` backend is used. Similar conventions are used to describe non-character -type values; for instance, *(3), * indicates that the default value for the indicated -key is 3, but any integer value can be provided. - -Most of the values associated with the various keys in the ``.par`` file are read by nekRS -and then saved to various arguments in the ``options`` data structure. The argument -is indicated in this section within square brackets. For example, -the value set by the ``backend`` key is stored in the ``THREAD MODEL`` argument -to ``options``. In other words, if you wanted to grab the value set by the user for the -``backend`` key, and save it in a local variable named ``user_occa_backend``, -you can use the ``getArgs`` function on the ``options`` data structure as follows. +Each of the keys and value types are described below. + +**TODO** Description of keys in table .. code-block:: cpp @@ -117,12 +100,6 @@ nekRS performs validation of the par file. Invalid sections, invalid keys or val invalid value combinations, missing values etc. will terminate the NekRS run with a clear error message. Deprecated attributes will be highlighted. -.. warning:: - - This user guide may quickly become out of date unless developers are careful to keep - the keys listed here up to date. A list of possible values is also given in - ``doc/parHelp.txt`` - nekRS uses just-in-time compilation to allow the incorporation of user-defined functions into program execution. These functions can be written to allow ultimate flexibility on the part of the user to affect the simulation, such as to define custom fluid properties, @@ -132,525 +109,12 @@ user-defined functions - see, for example, the ``viscosity`` key in the ``VELOCITY`` section. This parameter is used to set a constant viscosity, whereas for variable-property simulations, a user-defined function will override the ``viscosity`` input parameter. A full description of these user-defined functions on the host and -device are described in Sections :ref:`UDF Functions ` and -:ref:`OUDF Functions `. So, the description of valid (key, value) +device are described in Sections :ref:`udf_functions`. So, the description of valid (key, value) pairs here does not necessarily imply that these parameters reflect the full capabilities of nekRS. -``BOOMERAMG`` section -""""""""""""""""""""" - -This section is used to describe settings for the (optional) :term:`AMG` solver. - - * **coarsenType** [``BOOMERAMG COARSEN TYPE``] - - * **interpolationType** [``BOOMERAMG INTERPOLATION TYPE``] - - * **iterations** ** [``BOOMERAMG ITERATIONS``] - - * **nonGalerkinTol** [``BOOMERAMG NONGALERKIN TOLERANCE``] - - * **smootherType** [``BOOMERAMG SMOOTHER TYPE``] - - * **strongThreshold** ** [``BOOMERAMG NONGALERKIN TOLERANCE``] - -``GENERAL`` section -""""""""""""""""""" - -This section is used to describe generic settings for the simulation such as time steppers, -solution order, and file writing control. - -* **constFlowRate** ** [``"CONSTANT FLOW RATE = [value is provided]``] - - Set a constant flow rate in a given direction. Either ``meanVelocity`` or - ``meanVolumetricFlow`` must be provided to set the flow rate, - and either ``bid`` or ``direction`` must be provided to set the direction. - The following options are valid: - - * **meanVelocity** ** [``CONSTANT FLOW RATE TYPE = BULK``, ``FLOW RATE``] - - Sets the mean velocity. - - * **meanVelocity** ** [``CONSTANT FLOW RATE TYPE = VOLUMETRIC``, ``FLOW RATE``] - - Sets the mean volumetric flow rate. - - * **bid** *, * [``CONSTANT FLOW FROM BID``, ``CONSTANT FLOW TO BID``] - - Sets the flow direction based on two boundary IDs. - - * **direction** *x, y, z* [``CONSTANT FLOW DIRECTION``] - - Sets a flow direction parallel to the global coordinate axis. - -* **cubaturePolynomialOrder** ** [``CUBATURE POLYNOMIAL DEGREE``] - - Polynomial order for the cubature. If not specified, this defaults to the integer - closest to :math:`\frac{3}{2}(N + 1)` minus one, where :math:`N` is the polynomial - order. - - .. TODO: need better description of what cubature is - -* **dealiasing** *(true), false* - - If dealiasing is turned on, [``ADVECTION TYPE``] is set to ``CUBATURE+CONVECTIVE``, - whereas if dealiasing is turned off, [``ADVECTION TYPE``] is set to ``CUBATURE``. - - .. TODO: need better description of what dealiasing is -* **dt** ** [``DT``] - - Time step size. If any of the keyword options ``targetCFL``, ``max`` or ``initial`` - are specified (separated by ``+``), a variable timestep [``VARIABLE DT = TRUE``] - is used. Otherwise, ``dt`` is parsed as ``float`` and indicates the time step size. - - The following keywords may be given: - - * **targetCFL** *(0.5), * [``TARGET CFL``]: The target :term:`CFL` is also - used to set a default for the ``subCyclingSteps``. If not specified, it is given - by `max(subcyclingSteps*2, 0.5)``. - - * **max** *(0), * [``MAX DT``]: Largest allowed timestep. If 0 or unset, the - option is ignored. - - * **initial** *(0), * [initially written to ``DT``]: initial timestep. - -* **elapsedTime** ** [``STOP AT ELAPSED TIME``] - - Elapsed time at which to end the simulation, if using ``stopAt = elapsedTime``. - -* **endTime** ** [``END TIME``] - - Final time at which to end the simulation, if using ``stopAt = endTime``. - -* **numSteps** *(0), * [``NUMBER TIMESTEPS``] - - Number of time steps to perform, if using ``stopAt = numSteps``. By default, if not - specified, then it is assumed that no time steps are performed. - - -* **oudf** *[casename].oudf* [``UDF OKL FILE``] - - File name (including extension) of the ``*.oudf`` file, relative to the current directory. - By default, the stem of the ``*.par`` file is used as ``casename``. - -* **polynomialOrder** ** [``POLYNOMIAL DEGREE``] - - Polynomial order for the spectral element solution. An order of :math:`N` will result - in :math:`N+1` basis functions for each spatial dimension. The polynomial order is - currently limited to :math:`N < 10`. - -* **startFrom** ** [``RESTART FILE NAME``] - - Absolute or relative path to a nekRS output file from which to start the simulation from. - When used, the [``RESTART FROM FILE``] option argument is also set to true. - If the solution in the restart file was obtained with a different polynomial order, - interpolation is performed to the current simulation settings. To only read select fields - from the restart file (such as if you wanted to only apply the temperature solution from the - restart file to the present simulation), append ``+U`` (to read velocity), ``+P`` (to read pressure), - or ``+T`` (to read temperature) to the end of the restart file name. For instance, if the restart - file is named ``restart.fld``, using ``restart.fld+T`` will only read the temperature solution. - If ``startFrom`` is omitted, the simulation is assumed to start based on the user-defined initial conditions at time zero. - -* **stopAt** *(numSteps), elapsedTime, endTime* - - When to stop the simulation, either based on a number of time steps *numSteps*, a simulated - end time *endTime*, or a total elapsed wall time *elapsedTime*. If ``stopAt = numSteps``, - the ``numSteps`` parameter must be provided. If ``stopAt = endTime``, the ``endTime`` - parameter must be provided. If ``stopAt = elapsedTime``, the ``elapsedTime`` parameter - must be provided. - -* **subCyclingSteps** *(0), , auto* [``SUBCYCLING STEPS``] - - Number of subcycling steps; if ``dt: targetCFL`` is specified, the number of subcycling - steps is taken as the integer nearest to half the target :term:`CFL` as given by - the ``dt: targetCFL`` parameter. In this case, ``auto`` ensures that an error is raised - if ``dt: targetCFL`` is not specified. - - .. TODO: better description of what subcycling is - -* **timeStepper** *(tombo2), bdf1, bdf2, bdf3, tombo1, tombo3* [``TIME INTEGRATOR``] - - The method to use for time stepping. Note that - if you select any of the :term:`BDF` options, the time integrator is internally set to - the :term:`TOMBO` time integrator of equivalent order. - -* **udf** *[casename].udf* [``UDF FILE``] - - File name (including extension) of the ``*.udf`` file, relative to the current directory. - By default, the stem of the ``*.par`` file is used as ``casename``. - -* **usr** *[casename].usr* [``NEK USR FILE``] - - File name (including extension) of the ``*.usr`` file, relative to the current directory. - By default, the stem of the ``*.par`` file is used as ``casename``. - -* **verbose** *(false), true* [``VERBOSE``] - - Whether to print the simulation results in verbose format to the screen. - -* **writeControl** *(timeStep), runTime* [``SOLUTION OUTPUT COTROL``] - - Method to use for the writing of output files, either based on a time step interval with - *timeStep* (in which case ``SOLUTION OUTPUT CONTROL`` is set to ``STEPS``) - or a simulated time interval with *runTime* (in which case ``SOLUTION OUTPUT CONTROL`` - is set to ``RUNTIME``). - -* **writeInterval** ** [``SOLUTION OUTPUT INTERVAL``] - - Output writing frequency, either in units of time steps for ``writeControl = timeStep`` or - in units of simulation time for ``writeControl = runTime``. If a runtime step control is - used that does not perfectly align with the time steps of the simulation, nekRS will write - an output file on the timestep that most closely matches the desired write interval. - -Common keys -""""""""""" - -These parameters may be specified in any of the ``GENERAL``, ``VELOCITY``, ``TEMPERATURE`` and -``SCALARXX`` sections. If the parameter is not specified in any given ``VELOCITY``, -``TEMPERATURE`` or ``SCALARXX`` section, its values are usually inherited from the ``GENERAL`` -section. - -The key for the ``options`` structure listed here is the ``GENERAL`` key; in the other sections, -the key is prefixed with the section name. - -* **regularization** *("none"), * [``REGULARIZATION METHOD``] - - Filtering settings., options are separated by ``+``. This parameter is mutually exclusive - with the (deprecated) ``filtering`` parameter. The parameter may be specified in any of - the ``GENERAL``, ``VELOCITY``, ``TEMPERATURE`` and ``SCALARXX`` sections. If the parameter - is no specified in any given ``VELOCITY``, ``TEMPERATURE`` or ``SCALARXX`` section, - its values are inherited from the ``GENERAL`` section. - - Filtering is analogous to Nek5000; the ``hpfrt`` filter is described further in the - `Nek5000 documentation `__. - - The following examples for ``regularization`` are given in ``examples``: - - .. code-block:: ini - - # examples/turbPipePeriodic - regularization = hpfrt + nModes=1 + scalingCoeff=10 - - # examples/double_shear - regularization=avm+c0+highestModalDecay+scalingCoeff=0.5+rampconstant=1 - - * ``none``: regularization is disabled. - - * ``hpfrt``: High-pass filter. The following settings apply to this mode: - - * ``nmodes`` *(1), * [``HPFRT MODES``] - - Number of filtered modes :math:`(N-N')`, where :math:`(N)` is the - polynomial degree and :math:`(N')` the number of fully resolved modes. - - * ``cutoffratio`` ** - - Alternatively, the number of filtered modes can be given - by the cutoff ratio, where :math:`\frac{N'+1}{N+1} = {\tt filterCutoffRatio}`. - - * ``scalingcoeff`` *(1.0), * (required): [``HPFRT STRENGTH``] - - filter weight - - .. TODO: need better description of what filter weight is - - * ``avm+hpfResidual``: use HPF Residual :term:`AVM`, or ``avm+highestModalDecay``: - use Persson's highest modal decay AVM. - The AVM is described in [Persson]_, and only allowed for scalars. - If specified in ``GENERAL``, the ``regularization`` parameter must be overwritten in the - ``VELOCITY`` section. The following settings apply to these modes: - - * ``scalingcoeff`` *(1.0), * (required) [``REGULARIZATION SCALING COEFF``] - - filter weight - - * the ``nmodes``, ``cutoffratio`` and ``scalingcoeff`` parameters described above. With - ``HighestModalDecay`` mode, ``scalingcoeff`` is interpreted (and overwrites) as - ``vismaxcoeff``. - - * ``vismaxcoeff`` *(0.5), * [``REGULARIZATION VISMAX COEFF``]: - - controls maximum artificial viscosity - - * ``c0`` [``REGULARIZATION AVM C0``]: - - if provided, make viscosity C0 continous across elements - - * ``rampconstant`` *(1.0), * [``REGULARIZATION RAMP CONSTANT``]: - - controls ramp to maximum artificial viscosity - - -``MESH`` section -"""""""""""""""" - -This section is used to describe mesh settings and set up various mesh solvers -for mesh motion. - -**partitioner** [``MESH PARTITIONER``] - -**solver** *elasticity, none, user* - -If ``solver = none``, the mesh does not move and [``MOVING MESH``] is set to false. -Otherwise, the solver is stored in [``MESH SOLVER``]. When ``solver = user``, the -mesh moves according to a user-specified velocity. Alternatively, if -``solver = elasticity``, then the mesh motion is solved with an :term:`ALE` formulation. - -``OCCA`` section -"""""""""""""""" - -This section is used to specify the :term:`OCCA` backend for parallelization. - -**backend** *(CUDA), CPU, HIP, OPENCL, OPENMP, SERIAL* [``THREAD MODEL``] - -OCCA backend; ``CPU`` is the same as ``SERIAL``, and means that parallelism is achieved with -:term:`MPI`. - -**deviceNumber** *(LOCAL-RANK), * [``DEVICE NUMBER``] - -``PRESSURE`` section -"""""""""""""""""""" - -The ``PRESSURE`` section describes solve settings for the pressure equation. Note that -this block is only read if the ``VELOCITY`` block is also present. - -.. TODO: This section needs a lot more work describing all the parameters - -**downwardSmoother** *ASM, jacobi, RAS* [``PRESSURE MULTIGRID DOWNWARD SMOOTHER``] - -**galerkinCoarseOperator** ** [``GALERKIN COARSE OPERATOR``] - -**maxIterations** ** [``PRESSURE MAXIMUM ITERATIONS``] - -**pMultigridCoarsening** [``PRESSURE MULTIGRID COARSENING``] - -**preconditioner** *jacobi, multigrid, none, semfem, semg* [``PRESSURE PRECONDITIONER``] - -The pressure preconditioner to use; ``semg`` and ``multigrid`` both result -in a multigrid preconditioner. - -**residualProj** *(true), false* [``PRESSURE RESIDUAL PROJECTION``] - -**residualProjectionStart** ** [``PRESSURE RESIDUAL PROJECTION START``] - -**residualProjectionVectors** ** [``PRESSURE RESIDUAL PROJECTION VECTORS``] - -**residualTol** ** [``PRESSURE SOLVER TOLERANCE``] - -Absolute residual tolerance for the pressure solution - -**smootherType** *additive, asm, chebyshev, chebyshev+ras, chebyshev+asm, ras* [``PRESSURE MULTIGRID SMOOTHER``] - -**solver** - -**upwardSmoother** *ASM, JACOBI, RAS* [``PRESSURE MULTIGRID UPWARD SMOOTHER``] - -``PROBLEMTYPE`` section -""""""""""""""""""""""" - -This section is used to control the form of the governing equations used in nekRS. -While individual equations can be turned on/off in the ``VELOCITY``, ``TEMPERATURE``, -and ``SCALARXX`` sections, this block is used for higher-level control of the forms -of those equations themselves. - -**equation** *stokes* - -Whether to omit the advection term in the conservation of momentum equation, therefore -solving for the Stokes equations. If ``equation = stokes``, then -[``ADVECTION``] is set to false. - -**stressFormulation** *(false), true* [``STRESSFORMULATION``] - -Whether the viscosity (molecular plus turbulent) is not constant, therefore requiring -use of the full form of the viscous stress tensor :math:`\tau`. By setting ``stressFormulation = false``, -:math:`\nabla\cdot\tau` is represented as :math:`\nabla\cdot\tau=\mu\nabla^2\mathbf u`. -Even if the molecular viscosity is constant, this parameter must be set to ``true`` -when using a :term:`RANS` model because the turbulent viscosity portion of the overall -viscosity is not constant. - -``SCALARXX`` section -"""""""""""""""""""" - -This section is used to define the transport parameters and solver settings for each -passive scalar. For instance, in a simulation with two passive scalars, you would have -two sections - ``SCALAR01`` and ``SCALAR02``, each of which represents a passive scalar. - -**boundaryTypeMap** ** - -Array of strings describing the boundary condition to be applied to each sideset, ordered -by sideset ID. The valid characters/strings are shown in Table -:ref:`Passive Scalar Boundary Conditions `. - -**diffusivity** ** - -Although this is named ``diffusivity``, this parameter doubly represents the conductivity -governing diffusion of the passive scalar. In other words, the analogue from the -``TEMPERATURE`` section (a passive scalar in its internal representation) is the -``conductivity`` parameter. If a negative value is provided, the -conductivity is internally set to :math:`1/|k|`, where :math:`k` is the value of the -``conductivity`` key. If not specified, this defaults to :math:`1.0`. - -**residualProjection** ** - -**residualProjectionStart** ** - -**residualProjectionVectors** ** - -**residualTol** ** - -Absolute residual tolerance for the passive scalar solution - -**rho** ** - -Although this is name ``rho``, this parameter doubly represents the coefficient on the -total derivative of the passive scalar. In other words, the analogue from the -``TEMPERATURE`` section (a passive scalar in its internal representation) is the -``rhoCp`` parameter. If not specified, this defaults to :math:`1.0`. - -``TEMPERATURE`` section -""""""""""""""""""""""" - -This section is used to define the transport parameters and solver settings for the -temperature passive scalar. - -**boundaryTypeMap** ** - -Array of strings describing the boundary condition to be applied to each sideset, ordered -by sideset ID. The valid characters/strings are shown in Table -:ref:`Passive Scalar Boundary Conditions `. - -**conductivity** ** [``SCALAR00 DIFFUSIVITY``] - -Constant thermal conductivity; if a negative value is provided, the thermal conductivity -is internally set to :math:`1/|k|`, where :math:`k` is the value of the ``conductivity`` -key. If not specified, this defaults to :math:`1.0`. - -**residualProj** ** [``SCALAR00 RESIDUAL PROJECTION``] - -**residualProjectionStart** ** [``SCALAR00 RESIDUAL PROJECTION START``] - -**residualProjectionVectors** ** [``SCALAR00 RESIDUAL PROJECTION VECTORS``] - -**residualTol** ** [``SCALAR00 SOLVER TOLERANCE``] - -**rhoCp** ** [``SCALAR00 DENSITY``] - -Constant volumetric isobaric specific heat. If not specified, this defaults to :math:`1.0`. - -**solver** *none* - -You can turn off the solution of temperature by setting the solver to ``none``. - -``VELOCITY`` section -"""""""""""""""""""" - -This section is used to define the transport properties and solver settings for the -velocity. - -**boundaryTypeMap** ** - -Array of strings describing the boundary condition to be applied to each sideset, ordered -by sideset ID. The valid characters/strings are shown in Table -:ref:`Flow Boundary Conditions `. Note that no boundary conditions need to be -specified in the ``PRESSURE`` section, since the form of the pressure conditions are -specified in tandem with the velocity conditions with this parameter. - -**density** ** [``DENSITY``] - -Constant fluid density. If not specified, this defaults to :math:`1.0`. - -**maxIterations** *(200), * [``VELOCITY MAXIMUM ITERATIONS``] - -Maximum number of iterations for the velocity solve - -**residualProj** ** [``VELOCITY RESIDUAL PROJECTION``] - -**residualProjectionStart** ** [``VELOCITY RESIDUAL PROJECTION START``] - -**residualProjectionVectors** ** [``VELOCITY RESIDUAL PROJECTION VECTORS``] - -**residualTol** ** [``VELOCITY SOLVER TOLERANCE``] - -Absolute tolerance used for the velocity solve. - -**solver** *none* [``VELOCITY SOLVER``] - -You can turn off the solution of the flow (velocity and pressure) by setting the solver -to ``none``. Otherwise, if you omit ``solver`` entirely, the velocity solve will be turned on. -If you turn the velocity solve off, then you automatically also turn off the pressure solve. - -**viscosity** ** [``VISCOSITY``] - -Constant dynamic viscosity; if a negative value is provided, the dynamic viscosity is -internally set to :math:`1/|\mu|`, where :math:`\mu` is the value of the ``viscosity`` key. -If not specified, this defaults to :math:`1.0`. - -``CASEDATA`` section -"""""""""""""""""""" - -This section may be used to provide custom parameters in the ``.par`` file that are to be read -in the ``.udf`` file. For example, you may specify - -.. code-block:: ini - - [CASEDATA] - Re_tau = 550 - -in the ``.par`` file; the parameters should be read in the :ref:`UDF_Setup0 ` -function, e.g. - -.. code-block:: cpp - - static dfloat Re_tau; - platform->par->extract("casedata", "re_tau",Re_tau); - -NekRS does not check the contents of the ``CASEDATA`` section; such checks may be added in the -``UDF_Setup0`` function as well. - -Deprecated parameters -""""""""""""""""""""" - -``GENERAL`` section -^^^^^^^^^^^^^^^^^^^ - -* **filterCutoffRatio** ** [deprecated, see **regularization**] - - .. TODO: need better description of what filter cutoff ratio is - -* **filtering** *hpfrt* [deprecated, see **regularization**] - - If ``filtering = hpfrt``, [``FILTER STABILIZATION``] is set to ``RELAXATION``, - and ``filterWeight`` must be specified. If ``filtering`` is not specified, - [``FILTER STABILIZATION``] is set to ``NONE`` by default. - - .. TODO: need better description of what filtering is - -* **filterModes** ** [``HPFRT MODES``] [deprecated, see **regularization**] - - Number of filter modes; minimum value is 1. If not specified, the number of modes - is set by default to the nearest integer to :math:`(N+1)(1-f_c)`, where :math:`f_c` - is the filter cutoff ratio. - - .. TODO: need better description of what filter modes is - -* **filterWeight** ** [``HPFRT STRENGTH``] [deprecated, see **regularization**] - - .. TODO: need better description of what filter weight is - -Legacy Option (.rea) -"""""""""""""""""""" - -An alternative to the use of the ``.par`` file is to use the legacy Nek5000-based ``.rea`` file -to set up the case parameters. -See the ``Mesh File (.re2)`` section of the :term:`Nek5000` -`documentation `__ [#f1]_ -for further details on the format for the ``.rea`` file. - -The ``.rea`` file contains both simulation parameters (now covered by the ``.par`` file) as well -as mesh information (now covered by the ``.re2`` file). This section -here only describes the legacy approach to setting simulation parameters via the ``.rea`` file. - -.. TODO: describe the .rea file approach +.. literalinclude:: ../../parHelp.txt + :language: none Mesh File (.re2) ---------------- @@ -816,7 +280,7 @@ beginning the time stepping, and then once per time step after running each step Trigger Files (.upd) -------------------- -TODO Full description +**TODO** Full description Allows modifications to the simulation during execution. Can be edited and then notify of changes through sending a signal MPI rank 0. diff --git a/doc/source/user_guide/installing.rst b/doc/source/user_guide/installing.rst index 6310e4a00..0b621ad3f 100644 --- a/doc/source/user_guide/installing.rst +++ b/doc/source/user_guide/installing.rst @@ -84,7 +84,7 @@ be using a common package manager. .. code-block:: bash mpicc -show - mpif90 -show + mpifort -show .. tab:: MPICH @@ -110,7 +110,7 @@ be using a common package manager. .. code-block:: bash - export OMPI_CXX=/path/to/compiler/c_++_compiler + export OMPI_CXX=/path/to/compiler/c++_compiler export OMPI_CC=/path/to/compiler/c_compiler export OMPI_FC=/path/to/compiler/fortran_compiler @@ -118,10 +118,19 @@ be using a common package manager. .. code-block:: bash - export MPICH_CXX=/path/to/compiler/c_++_compiler + export MPICH_CXX=/path/to/compiler/c++_compiler export MPICH_CC=/path/to/compiler/c_compiler export MPICH_FC=/path/to/compiler/fortran_compiler + For example if using the GNU compilers with Open MPI on Ubuntu 22.04 this + is likely to be set with: + + .. code-block:: bash + + export OMPI_CXX=/usr/bin/g++ + export OMPI_CC=/usr/bin/gcc + export OMPI_FC=/usr/bin/gfortran + It is also suggested that you have a GPU and the corresponding drivers/API installed to increase performance. This will likely be a NVidia (:term:`CUDA`), :term:`AMD` (:term:`HIP`), Intel (:term:`DPC++`/:term:`oneAPI`) or Apple diff --git a/doc/source/user_guide/intro.rst b/doc/source/user_guide/intro.rst index 21adf71c9..505109562 100644 --- a/doc/source/user_guide/intro.rst +++ b/doc/source/user_guide/intro.rst @@ -133,7 +133,7 @@ Memory management is done through the C++ API which allows the user to make data available on the compute backend device (sometimes referred to as the device) and copy data into this for future use. -TODO - explanation of any automatic copying?? +**TODO** - explanation of any automatic copying?? Typically, relevant fields should be created and initialised in the `UDF_loadKernels` function: diff --git a/doc/source/user_guide/meshing.rst b/doc/source/user_guide/meshing.rst index 8560a5ca5..29b91f9c6 100644 --- a/doc/source/user_guide/meshing.rst +++ b/doc/source/user_guide/meshing.rst @@ -24,14 +24,14 @@ if using them, with further information also available in the Mesh with Cubit --------------- -TODO Example of creating Exodus Mesh +**TODO** Example of creating Exodus Mesh .. _gmsh_mesh: Meshing with Gmsh ----------------- -TODO Example of creating a Gmsh mesh +**TODO** Example of creating a Gmsh mesh All your mesh should be hexahedral elements. Before exporting from Gmsh, you will need to set the mesh order to 2. The Gmsh mesh format must also be version 2, ASCII/binary format. If your Gmsh version @@ -43,7 +43,7 @@ or "Save parametric elements". Creating a mesh with ?????? - CGNS ---------------------------------- -TODO Example of creating a cgns mesh +**TODO** Example of creating a cgns mesh .. _cht_mesh: diff --git a/doc/source/user_guide/postprocessing.rst b/doc/source/user_guide/postprocessing.rst index fa2d03a07..96a19ef88 100644 --- a/doc/source/user_guide/postprocessing.rst +++ b/doc/source/user_guide/postprocessing.rst @@ -11,26 +11,6 @@ tool such as Paraview or Visit. However, additional data or derived values can be extracted by setting up User Defined outputs using the ``UDF_ExecuteStep`` function of the ``.udf`` file. -The ``UDF_ExecuteStep`` function is called at the start of the simulation and -once per time step. Therefore, to ensure good performance you must check the -time status of the execution for any potential functionality. E.G. you can -check the current step should be used for checkpointing with the -``nrs->isCheckpointStep`` method, or calculate values at a specific frequency -by checking the ``tstep`` integer parameter with a modulus operation. - -.. code-block:: - - void UDF_ExecuteStep(double time, int tstep) - { - if (nrs->isCheckpointStep) { - // code here - } - - if (tstep % 100 == 0) { - // code here - } - } - .. _checkpointing_visualisation: Checkpointing & Visualization @@ -44,10 +24,11 @@ These output files are in a custom binary format that requires a ``.nek500 file to be viewable in Paraview (or similar tools). This should be automatically generated by NekRS, but can also be manually created using the ``nrsvis`` script. +.. _compute_derived: + Compute Derived Quantity ------------------------ - Additional control of the simulation to compute additional/derived quantities or output custom fields can be achieved by utilising the ``UDF_ExecuteStep`` function of the ``.udf`` file. Here we demonstrate how this can be used to @@ -55,16 +36,25 @@ compute a derived quantity and output custom fields. Qcriterion in turbPipe example -Example??? +.. _custom_checkpoint: Adding Custom Checkpoint Fields ------------------------------- -nrs->addUserCheckpointField("scalar01", std::vector>{o_nuAVM}); +.. code-block:: cpp + + nrs->addUserCheckpointField("scalar01", std::vector>{o_nuAVM}); Adding Custom Output File ------------------------- +.. code-block:: cpp + + iofld = iofldFactory::create(); + iofld->open(mesh, iofld::mode::write, "qcrit"); + iofld->writeAttribute("uniform", "true"); + iofld->writeAttribute("polynomialOrder", std::to_string(mesh->N + 2)); + iofld->process(); .. _turbulence_stats: diff --git a/doc/source/user_guide/running.rst b/doc/source/user_guide/running.rst index 81ba2ac0d..7aca42e07 100644 --- a/doc/source/user_guide/running.rst +++ b/doc/source/user_guide/running.rst @@ -57,4 +57,4 @@ scripts and their usage is as follows. Queueing system --------------- -TODO +**TODO**