diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 97032783b..ebe025a1e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -40,7 +40,7 @@ jobs: - name: Report run: | echo "::add-matcher::.github/problem-matchers/sphinx.json" - egrep "WARNING:" build-output.txt | sort | uniq | \ + egrep "WARNING:|Warning:|ERROR:|Error:" build-output.txt | sort | uniq | \ awk 'BEGIN{i=0}{print $0}{i++}END{print "Warnings: "i}' > build-output-warnings.txt cat build-output-warnings.txt exit $(tail -n 1 build-output-warnings.txt | awk '{print $2}') diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py index c95cf099d..fadf6555c 100644 --- a/docs/sphinx/conf.py +++ b/docs/sphinx/conf.py @@ -15,8 +15,10 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -import os -import sys +# import os +#import sys +# sys.path.insert(0, os.path.abspath('.')) +#sys.path.append("../breathe") # -- General configuration ------------------------------------------------ @@ -27,20 +29,14 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.autosummary', - 'sphinx.ext.mathjax', - 'sphinx.ext.intersphinx', - 'sphinxcontrib.bibtex', - ] +extensions = ['sphinx.ext.mathjax', 'sphinxcontrib.bibtex'] bibtex_bibfiles = ['references/references.bib'] -autodoc_default_flags = ['members','show-inheritance','undoc-members'] -autoclass_content = 'both' -mathjax_path = 'https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML' -numfig = True + + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] +#breathe_projects = {"Nalu-Wind": "../doxygen_output/xml/"} +#breathe_default_project = "Nalu-Wind" #fortran_src ='../../src/' #fortran_ext =[' 'F90'] @@ -352,9 +348,7 @@ # # texinfo_no_detailmenu = False -primary_domain = "cpp" - def setup(app): app.add_object_type("inpfile", "inpfile", - objname="Nalu-Wind Input File Parameter", - indextemplate="pair: %s; Nalu-Wind Input File Parameter") + objname="Nalu-Wind input parameter", + indextemplate="pair: %s; Nalu-Wind input parameter") diff --git a/docs/sphinx/source/developer/write_developer_doc.rst b/docs/sphinx/source/developer/write_developer_doc.rst index 53b47a6ad..a494abaa1 100644 --- a/docs/sphinx/source/developer/write_developer_doc.rst +++ b/docs/sphinx/source/developer/write_developer_doc.rst @@ -18,12 +18,3 @@ copy of the file. .. literalinclude:: dox_example/example.h :language: c++ :caption: Sample C++ header file showing inline documentation using specially formatted comments. - -Once processed by Doxygen and embedded in Sphinx, the resulting documentation of -the class looks as shown below: - -.. doxygenclass:: ExampleClass - :project: example_cpp - :members: - :private-members: - :protected-members: diff --git a/docs/sphinx/source/theory/windEnergy.rst b/docs/sphinx/source/theory/windEnergy.rst index 3be8c0e7a..978594427 100644 --- a/docs/sphinx/source/theory/windEnergy.rst +++ b/docs/sphinx/source/theory/windEnergy.rst @@ -329,7 +329,7 @@ Initial conditions Nalu-Wind has the ability to initialize the internal flow fields to uniform conditions for all pressure, velocity, temperature, and TKE (:math:`k`) in the -:inpfile:`input file `. Nalu-Wind also provides a *user +`input file `. Nalu-Wind also provides a *user function* to add perturbations to the velocity field to trigger turbulence generation during precursor simulations. To specify more complex flow field conditions, a temperature profile with a capping inversion for example, users diff --git a/docs/sphinx/source/user/nalu_run/abl_forcing.rst b/docs/sphinx/source/user/nalu_run/abl_forcing.rst deleted file mode 100644 index a42a257ed..000000000 --- a/docs/sphinx/source/user/nalu_run/abl_forcing.rst +++ /dev/null @@ -1,152 +0,0 @@ -ABL Forcing -```````````````````` - -.. inpfile:: abl_forcing - - ``abl_forcing`` allows the user to specify desired velocities - and temperatures at different heights. - These velocities and temperatures are enforced through the - use of source in the momentum and enthalpy equations. - The ``abl_forcing`` option needs to be specified in the - ``momentum`` and/or ``enthalpy`` source blocks: - - .. code-block:: yaml - - - source_terms: - momentum: abl_forcing - enthalpy: abl_forcing - - This option allows the code to implement source terms - in the momentum and/or enthalpy equations. - A sample - section is shown below - - .. code-block:: yaml - - abl_forcing: - search_method: stk_kdtree - search_tolerance: 0.0001 - search_expansion_factor: 1.5 - output_frequency: 1 - - from_target_part: [fluid_part] - - momentum: - type: computed - relaxation_factor: 1.0 - heights: [250.0, 500.0, 750.0] - target_part_format: "zplane_%06.1f" - - # The velocities at each plane - # Each list include a time and the velocities for each plane - # Notice that the total number of elements in each list will be - # number of planes + 1 - velocity_x: - - [0.0, 10.0, 5.0, 15.0] - - [100000.0, 10.0, 5.0, 15.0] - - velocity_y: - - [0.0, 0.0, 0.0, 0.0] - - [100000.0, 0.0, 0.0, 0.0] - - velocity_z: - - [0.0, 0.0, 0.0, 0.0] - - [100000.0, 0.0, 0.0, 0.0] - - temperature: - type: computed - relaxation_factor: 1.0 - heights: [250.0, 500.0, 750.0] - target_part_format: "zplane_%06.1f" - - temperature: - - [0.0, 300.0, 280.0, 310.0] - - [100000.0, 300.0, 280.0, 310.0] -.. note:: - - The variables in the :inpfile:`abl_forcing` subsection are - prefixed with ``abl_forcing.name`` but only the variable - name after the period should appear in the input file. - -.. inpfile:: abl_forcing.search_method - - This specifies the search method algorithm within the - stk framework. The default option `stk_kdtree` is recommended. - -.. inpfile:: abl_forcing.search_tolerance - - This is the tolerance specified for the - `search_method` algorithm. A default value of 0.0001 is recommended. - -.. inpfile:: abl_forcing.search_expansion_factor - - This option is related to the stk search algorithm. - A value of 1.5 is recommended. - -.. inpfile:: abl_forcing.output_frequency - - This is the frequency at which the source term is written - to the output value. A value of 1 means the source term - will be written to the output file every time-step. - -.. note:: - - There are now two options in the following inputs. - The can be ``momentum`` and/or ``temperature``. - -.. inpfile:: abl_forcing.momentum.computed - - This option allows the user to choose if a momentum source is computed - from a desired velocity (``computed``) or if a user defined - source term is directly - applied into the momentum equation (``user_defined``). - -.. inpfile:: abl_forcing.momentum.relaxation_factor - - This is a relaxation factor which can be used to under/over-relax - the momentum source term. - The default value is 1. - -.. inpfile:: abl_forcing.momentum.heights - - This is a list containing the planes at which the forcing should - be implemented. Each input is the height for that plane. - This is the naming convention in the mesh file. - -.. inpfile:: abl_forcing.momentum.target_part_format - - This is the format in which the planes are saved in the - mesh file. - -.. inpfile:: abl_forcing.momentum.velocity_x - - A set of lists containing the time in the first element, - followed by the desired velocity at each plane in the - :math:`x` direction. - -.. inpfile:: abl_forcing.momentum.velocity_y - - A set of lists containing the time in the first element, - followed by the desired velocity at each plane in the - :math:`y` direction. - - -.. inpfile:: abl_forcing.momentum.velocity_z - - A set of lists containing the time in the first element, - followed by the desired velocity at each plane in the - :math:`z` direction. - -.. note:: - - The temperature has the same inputs as the momentum source - (``abl_forcing.temperature.type``, - ``abl_forcing.temperature.relaxation_factor``, - ``abl_forcing.temperature.heights``, and - ``abl_forcing.temperature.target_part_format``) - which take the same options. - -.. inpfile:: abl_forcing.temperature.temperature - - A set of lists containing the time in the first element, - followed by the desired temperature at each plane. diff --git a/docs/sphinx/source/user/nalu_run/nalu_inp.rst b/docs/sphinx/source/user/nalu_run/nalu_inp.rst index f9b0cdc27..0f0af36a1 100644 --- a/docs/sphinx/source/user/nalu_run/nalu_inp.rst +++ b/docs/sphinx/source/user/nalu_run/nalu_inp.rst @@ -41,7 +41,7 @@ simulation to be executed. other realms. In this context, it acts as an *output* realm. Inclusion of an input/output realm will require the user to provide the - additional :inpfile:`transfers` section in the Nalu-Wind input file that defines + additional `transfers` section in the Nalu-Wind input file that defines the solution fields that are transferred between the realms. See :ref:`nalu_inp_realm` for detailed documentation on all Realm options. @@ -58,14 +58,14 @@ simulation to be executed. This section configures the time integration scheme used (first/second order in time), the duration of simulation, fixed or adaptive timestepping based on Courant number constraints, etc. Each time integration section in this list - can accept one or more :inpfile:`realms` that are integrated in time using + can accept one or more `realms` that are integrated in time using that specific time integration scheme. See :ref:`nalu_inp_time_integrators` for complete documentation of all time integration options available in Nalu-Wind. **Transfers** An optional section that defines one or more solution transfer definitions - between the participating :inpfile:`realms` during the simulation. Each + between the participating `realms` during the simulation. Each transfer definition provides a mapping of the to and from realm, part, and the solution field that must be transferred at every timestep during the simulation. See :ref:`nalu_inp_transfers` section for complete documentation of @@ -88,14 +88,14 @@ entries: .. note:: - The variable in the :inpfile:`linear_solvers` subsection are prefixed with + The variable in the `linear_solvers` subsection are prefixed with ``linear_solvers.name`` but only the variable name after the period should appear in the input file. .. inpfile:: linear_solvers.name The key used to refer to the linear solver configuration in - :inpfile:`equation_systems.solver_system_specification` section. + `equation_systems.solver_system_specification` section. .. inpfile:: linear_solvers.type @@ -112,7 +112,7 @@ entries: The solver used for solving the linear system. - When :inpfile:`linear_solvers.type` is ``tpetra`` the valid options are: + When `linear_solvers.type` is ``tpetra`` the valid options are: ``gmres``, ``biCgStab``, ``cg``. For ``hypre`` the valid options are ``hypre_boomerAMG`` and ``hypre_gmres``. @@ -122,7 +122,7 @@ entries: The type of preconditioner used. - When :inpfile:`linear_solvers.type` is ``tpetra`` the valid options are + When `linear_solvers.type` is ``tpetra`` the valid options are ``sgs``, ``mt_sgs``, ``muelu``. For ``hypre`` the valid options are ``boomerAMG`` or ``none``. @@ -152,7 +152,7 @@ entries: .. inpfile:: linear_solvers.muelu_xml_file_name - Only used when the :inpfile:`linear_solvers.preconditioner` is set to + Only used when the `linear_solvers.preconditioner` is set to ``muelu`` and specifies the path to the XML filename that contains various configuration parameters for Trilinos MueLu package. @@ -219,7 +219,7 @@ Time Integration Options .. inpfile:: Time_Integrators - A list of time-integration options used to advance the :inpfile:`realms` in + A list of time-integration options used to advance the `realms` in time. Each list entry must contain a YAML mapping with the key indicating the type of time integrator. Currently only one option, ``StandardTimeIntegrator`` is available. @@ -242,7 +242,7 @@ Time Integration Options .. inpfile:: time_int.name The lookup key for this time integration entry. This name must match the one - provided in :inpfile:`Simulations` section. + provided in `Simulations` section. .. inpfile:: time_int.termination_time @@ -251,24 +251,24 @@ Time Integration Options .. inpfile:: time_int.termination_step_count Nalu-Wind will stop the simulation once the specified ``termination_step_count`` - timesteps have been completed. If both :inpfile:`time_int.termination_time` + timesteps have been completed. If both `time_int.termination_time` and this parameter are provided then this parameter will prevail. .. inpfile:: time_int.time_step The time step (:math:`\Delta t`) used for the simulation. If - :inpfile:`time_int.time_stepping_type` is ``fixed`` this value does not + `time_int.time_stepping_type` is ``fixed`` this value does not change during the simulation. .. inpfile:: time_int.start_time The starting time step (default: ``0.0``) when starting a new simulation. Note that this has no effect on restart which is controlled by - :inpfile:`restart.restart_time` in the :inpfile:`restart` section. + `restart.restart_time` in the :inpfile:`restart` section. .. inpfile:: time_int.time_step_count - The starting timestep counter for a new simulation. See :inpfile:`restart` + The starting timestep counter for a new simulation. See `restart` for restarting from a previous simulation. .. inpfile:: time_int.second_order_accuracy @@ -280,17 +280,17 @@ Time Integration Options One of ``fixed`` or ``adaptive`` indicating whether a fixed time-stepping scheme or an adaptive timestepping scheme is used for simulations. See - :inpfile:`time_step_control` for more information on max Courant number based + `time_step_control` for more information on max Courant number based adaptive time stepping. .. inpfile:: time_int.realms - A list of :inpfile:`realms` names. The names entered here must match - :inpfile:`name` used in the :inpfile:`realms` section. Names listed here not - found in :inpfile:`realms` list will trigger an error, while realms not - included in this list but present in :inpfile:`realms` will not be + A list of `realms` names. The names entered here must match + `name` used in the `realms` section. Names listed here not + found in `realms` list will trigger an error, while realms not + included in this list but present in `realms` will not be initialized and silently ignored. This can cause the code to abort if the - user attempts to access the specific realm in the :inpfile:`transfers` + user attempts to access the specific realm in the `transfers` section. .. _nalu_inp_realm: @@ -298,7 +298,7 @@ Time Integration Options Physics Realm Options ~~~~~~~~~~~~~~~~~~~~~~~ -As mentioned previously, :inpfile:`realms` is a YAML list data structure +As mentioned previously, `realms` is a YAML list data structure containing at least one :ref:`nalu_inp_realm` entry that defines the computational domain (provided as an Exodus-II mesh), the set of physics equations that must be solved over this domain, along with the necessary initial @@ -309,16 +309,16 @@ in the input file are =============================== ========================================================================= Realm subsection Purpose =============================== ========================================================================= -:inpfile:`equation_systems` Set of physics equations to be solved -:inpfile:`initial_conditions` Initial conditions for the various fields -:inpfile:`boundary_conditions` Boundary condition for the different fields -:inpfile:`material_properties` Material properties (e.g., fluid density, viscosity etc.) -:inpfile:`solution_options` Discretization and numerical stability -:inpfile:`mesh_transformation` Mesh transformation -:inpfile:`mesh_motion` Mesh motion -:inpfile:`output` Solution output options (file, frequency, etc.) -:inpfile:`restart` Optional: Restart options (restart time, checkpoint frequency etc.) -:inpfile:`time_step_control` Optional: Parameters determining variable timestepping +`equation_systems` Set of physics equations to be solved +`initial_conditions` Initial conditions for the various fields +`boundary_conditions` Boundary condition for the different fields +`material_properties` Material properties (e.g., fluid density, viscosity etc.) +`solution_options` Discretization and numerical stability +`mesh_transformation` Mesh transformation +`mesh_motion` Mesh motion +`output` Solution output options (file, frequency, etc.) +`restart` Optional: Restart options (restart time, checkpoint frequency etc.) +`time_step_control` Optional: Parameters determining variable timestepping =============================== ========================================================================= In addition to the sections mentioned in the table, there are several additional @@ -329,13 +329,13 @@ optional sections are provided below: ==================================== =========================================================================== Realm subsection Purpose ==================================== =========================================================================== -:inpfile:`turbulence_averaging` Generate statistics for the flow field -:inpfile:`post_processing` Extract integrated data from the simulation -:inpfile:`solution_norm` Compare the solution error to a reference solution -:inpfile:`data_probes` Extract data using probes -:inpfile:`actuator` Model turbine blades/tower using actuator lines -:inpfile:`abl_forcing` Momentum source term to drive ABL flows to a desired velocity profile -:inpfile:`boundary_layer_statistics` Compute boundary layer statistics +`turbulence_averaging` Generate statistics for the flow field +`post_processing` Extract integrated data from the simulation +`solution_norm` Compare the solution error to a reference solution +`data_probes` Extract data using probes +`actuator` Model turbine blades/tower using actuator lines +`abl_forcing` Momentum source term to drive ABL flows to a desired velocity profile +`boundary_layer_statistics` Compute boundary layer statistics ==================================== =========================================================================== @@ -345,7 +345,7 @@ Common options .. inpfile:: name The name of the realm. The name provided here is used in the - :inpfile:`Time_Integrators` section to determine the time-integration scheme + `Time_Integrators` section to determine the time-integration scheme used for this computational domain. .. inpfile:: mesh @@ -384,7 +384,7 @@ Common options .. inpfile:: polynomial_order An integer value indicating the polynomial order used for higher-order mesh - simulations. The default value is ``1``. When :inpfile:`polynomial_order` is + simulations. The default value is ``1``. When `polynomial_order` is greater than 1, the Realm has the capability to promote the mesh to higher-order during initialization. @@ -415,8 +415,8 @@ Common options .. inpfile:: balance_nodes A boolean flag indicating whether node balancing is performed during - simulations. See also :inpfile:`balance_node_iterations` and - :inpfile:`balance_nodes_target`. + simulations. See also `balance_node_iterations` and + `balance_nodes_target`. .. inpfile:: balance_node_iterations @@ -438,7 +438,7 @@ Equation Systems .. note:: - The variable in the :inpfile:`equation_systems` subsection are prefixed with + The variable in the `equation_systems` subsection are prefixed with ``equation_systems.name`` but only the variable name after the period should appear in the input file. @@ -465,7 +465,7 @@ Equation Systems The above example indicates that the linear systems for the enthalpy and momentum (velocity) equations are solved by the linear solver corresponding - to the tag ``solve_scalar`` in the :inpfile:`linear_systems` entry, whereas + to the tag ``solve_scalar`` in the `linear_systems` entry, whereas the continuity equation system (pressure Poisson solve) should be solved using the linear solver definition corresponding to the tag ``solve_continuity``. @@ -549,7 +549,7 @@ Initial conditions This input parameter serves two purposes: 1. it indicates the *type* (``constant``), and 2. provides the custom *name* for this condition. In - addition to the :inpfile:`initial_conditions.target_name` this section + addition to the `initial_conditions.target_name` this section requires another entry ``value`` that contains the mapping of ``(field_name, value)`` as shown in the above example. @@ -582,7 +582,7 @@ Boundary Conditions - ``non_conformal`` -- e.g., BC across sliding mesh interfaces - ``overset`` -- overset mesh assembly description -All BC types require :inpfile:`bc.target_name` that contains a list of side sets +All BC types require `bc.target_name` that contains a list of side sets where the specified BC is to be applied. Additional information necessary for certain BC types are provided by a sub-dictionary with the key ``_user_data:`` that contains the parameters necessary to initialize a @@ -642,16 +642,16 @@ details on the actual implementation. gravity_vector_component: 3 reference_temperature: 300.0 -The entry :inpfile:`gravity_vector_component` is an integer that +The entry `gravity_vector_component` is an integer that specifies the component of the gravity vector, defined in -:inpfile:`solution_options.gravity`, that should be used in the +`solution_options.gravity`, that should be used in the definition of the Monin-Obukhov length scale calculation. The -entry :inpfile:`reference_temperature` is the reference temperature +entry `reference_temperature` is the reference temperature used in calculation of the Monin-Obukhov length scale. When there is mesh motion involved the wall boundary velocity takes the value of -the mesh_velocity along the part represented by :inpfile:`bc.target_name`. In -such a scenario all information under :inpfile:`bc.wall_user_data` is rendered +the mesh_velocity along the part represented by `bc.target_name`. In +such a scenario all information under `bc.wall_user_data` is rendered unused. Example of wall boundary with a custom user function for temperature at the wall @@ -667,7 +667,7 @@ Example of wall boundary with a custom user function for temperature at the wall Symmetry Boundary Condition +++++++++++++++++++++++++++ -Requires no additional input other than :inpfile:`bc.target_name`. +Requires no additional input other than `bc.target_name`. .. code-block:: yaml @@ -679,11 +679,11 @@ Requires no additional input other than :inpfile:`bc.target_name`. Periodic Boundary Condition +++++++++++++++++++++++++++ -Unlike the other BCs described so far, the parameter :inpfile:`bc.target_name` +Unlike the other BCs described so far, the parameter `bc.target_name` behaves differently for the periodic BC. This parameter must be a list containing exactly two entries: the boundary face pair where periodicity is enforced. The nodes on these planes must coincide after translation in the -direction of periodicity. This BC also requires a :inpfile:`periodic_user_data` +direction of periodicity. This BC also requires a `periodic_user_data` section that specifies the search tolerance for locating node pairs. .. inpfile:: periodic_user_data @@ -698,7 +698,7 @@ section that specifies the search tolerance for locating node pairs. Non-Conformal Boundary ++++++++++++++++++++++ -Like the periodic BC, the parameter :inpfile:`bc.target_name` must be a list +Like the periodic BC, the parameter `bc.target_name` must be a list with exactly two entries that specify the boundary plane pair forming the non-conformal boundary. @@ -746,7 +746,7 @@ Material Properties A list of element blocks (*parts*) where the material properties are applied. This list should ideally include all the parts that are referenced by - :inpfile:`initial_conditions.target_name`. Using the alias ``all_blocks`` is + `initial_conditions.target_name`. Using the alias ``all_blocks`` is equivalent to listing all element blocks in the mesh. .. inpfile:: material_properties.constant_specification @@ -824,7 +824,7 @@ Material Properties - species_name: Air coefficients: [1.7894e-5, 273.11, 110.56] - The ``species_name`` must correspond to the entry in :inpfile:`reference + The ``species_name`` must correspond to the entry in `reference quantitites ` to lookup molecular weight information. @@ -929,7 +929,7 @@ Mesh Transformation .. inpfile:: mesh_transformation This subsection of the realm describes a one time stationary motion undergone - by the entire mesh with entries under :inpfile:`mesh_transformation` describing + by the entire mesh with entries under `mesh_transformation` describing the motions applied to different parts in a. Example: @@ -970,7 +970,7 @@ Mesh Motion .. inpfile:: mesh_motion This subsection of the of the realm describes the time-dependent rigid body motion undergone - by the entire mesh for as described by entries under :inpfile:`mesh_motion`. + by the entire mesh for as described by entries under `mesh_motion`. Example: @@ -1068,23 +1068,23 @@ Restart Options .. inpfile:: restart.restart_data_base_name - The filename for restart. Like :inpfile:`output`, the filename can contain a + The filename for restart. Like `output`, the filename can contain a directory and it will be created if not already present. .. inpfile:: restart.restart_time If this variable is present, it indicates that the current run will restart - from a previous simulation. This requires that the :inpfile:`mesh` be a + from a previous simulation. This requires that the `mesh` be a restart file with all the fields necessary for the equation sets defined in - the :inpfile:`equation_systems.systems`. Nalu-Wind will restart from the closest - time available in the :inpfile:`mesh` to ``restart_time``. The timesteps + the `equation_systems.systems`. Nalu-Wind will restart from the closest + time available in the `mesh` to ``restart_time``. The timesteps available in a restart file can be examined by looking at the ``time_whole`` variable using the ``ncdump`` utility. .. note:: The restart database used for restarting a simulation is the - :inpfile:`mesh` parameter. The :inpfile:`restart_data_base_name + `mesh` parameter. The :inpfile:`restart_data_base_name ` parameter is used exclusively for outputs. @@ -1118,7 +1118,7 @@ Time-step Control Options .. inpfile:: time_step_control This optional section specifies the adpative time stepping parameters used if - :inpfile:`time_int.time_stepping_type` is set to ``adaptive``. + `time_int.time_stepping_type` is set to ``adaptive``. .. code-block:: yaml @@ -1137,7 +1137,202 @@ Time-step Control Options **Turbine specific input options** -.. include:: ./turbine_modeling.rst +Actuator Turbine Model +`````````````````````` + +.. inpfile:: actuator + + ``actuator`` subsection defines the inputs for actuator line simulations. A + sample section is shown below for running actuator line simulations + coupled to OpenFAST with two turbines. + +.. code-block:: yaml + + actuator: + type: ActLineFAST + search_method: stk_kdtree + search_target_part: Unspecified-2-HEX + + n_turbines_glob: 2 + dry_run: False + debug: False + t_start: 0.0 + simStart: init # init/trueRestart/restartDriverInitFAST + t_max: 5.0 + n_every_checkpoint: 100 + + Turbine0: + procNo: 0 + num_force_pts_blade: 50 + num_force_pts_tower: 20 + nacelle_cd: 1.0 + nacelle_area: 1.0 + air_density: 1.225 + epsilon: [ 5.0, 5.0, 5.0 ] + turbine_base_pos: [ 0.0, 0.0, -90.0 ] + turbine_hub_pos: [ 0.0, 0.0, 0.0 ] + restart_filename: "" + FAST_input_filename: "Test01.fst" + turb_id: 1 + turbine_name: machine_zero + + Turbine1: + procNo: 0 + num_force_pts_blade: 50 + num_force_pts_tower: 20 + nacelle_cd: 1.0 + nacelle_area: 1.0 + air_density: 1.225 + epsilon: [ 5.0, 5.0, 5.0 ] + turbine_base_pos: [ 250.0, 0.0, -90.0 ] + turbine_hub_pos: [ 250.0, 0.0, 0.0 ] + restart_filename: "" + FAST_input_filename: "Test02.fst" + turb_id: 2 + turbine_name: machine_one + + +.. inpfile:: actuator.type + + Type of actuator source. Options are ``ActLineFAST`` and ``ActDiskFAST``. ``ActLineFAST`` is for actuator lines, and ``ActDiskFAST`` is for actuator disks. The actuator disk uses a stationary actuator line model to compute forces at the blade locations and then the average force of the blades is spread azimuthally between the blades sampling points. + +.. inpfile:: actuator.search_method + + String specifying the type of search method used to identify the nodes within the search radius of the actuator points. The only valid option is ``stk_kdtree``. The ``boost_rtree`` option has been deprecated by the STK search library. + +.. inpfile:: search_target_part + + String or an array of strings specifying the parts of the mesh to be searched to identify the nodes near the actuator points. + +.. inpfile:: actuator.n_turbines_glob + + Total number of turbines in the simulation. The input file must contain a number of turbine specific sections (`Turbine0`, `Turbine1`, ..., `Turbine(n-1)`) that is consistent with `nTurbinesGlob`. + +.. inpfile:: actuator.debug + + Enable debug outputs if set to true + +.. inpfile:: actuator.dry_run + + The simulation will not run if dryRun is set to true. However, the simulation will read the input files, allocate turbines to processors and prepare to run the individual turbine instances. This flag is useful to test the setup of the simulation before running it. + +.. inpfile:: actuator.simStart + + Flag indicating whether the simulation starts from scratch or restart. ``simStart`` takes on one of three values: + + * ``init`` - Use this option when starting a simulation from `t=0s`. + * ``trueRestart`` - While OpenFAST allows for restart of a turbine simulation, external components like the Bladed style controller may not. Use this option when all components of the simulation are known to restart. + * ``restartDriverInitFAST`` - When the ``restartDriverInitFAST`` option is selected, the individual turbine models start from `t=0s` and run up to the specified restart time using the inflow data stored at the actuator nodes from a hdf5 file. The C++ API stores the inflow data at the actuator nodes in a hdf5 file at every OpenFAST time step and then reads it back when using this restart option. This restart option is especially useful when the glue code is a CFD solver. + +.. inpfile:: actuator.t_start + + Start time of the simulation + +.. inpfile:: actuator.t_end + + End time of the simulation. ``t_end`` <= ``t_max`` + +.. inpfile:: actuator.t_max + + Max time of the simulation + + +.. note:: + + ``t_max`` can only be set when OpenFAST is running from `t=0s` and ``simStart`` is ``init``. ``t_max`` can not be changed on a restart. OpenFAST will not be able to run beyond ``t_max``. Choose ``t_max`` to be large enough to accomodate any possible future extensions of runs. One can change ``t_start`` and ``t_end`` to start and stop the simulation any number of times as long as ``t_end`` <= ``t_max``. + +.. inpfile:: actuator.dt_fast + + Time step for OpenFAST. All turbines should have the same time step. + +.. inpfile:: actuator.n_every_checkpoint + + Restart files will be written every so many time steps + +**Turbine specific input options** + +.. inpfile:: actuator.turbine_base_pos + + The position of the turbine base for actuator-line/disk simulations + +.. inpfile:: actuator.num_force_pts_blade + + The number of actuator points along each blade for actuator-line/disk simulations + +.. inpfile:: actuator.num_force_pts_tower + + The number of actuator points along the tower for actuator-line/disk simulations. + +.. inpfile:: actuator.nacelle_cd + + The drag coefficient for the nacelle. If this is set to zero, or not + defined, the code will not implement the nacelle model. + +.. inpfile:: actuator.nacelle_area + + The reference area for the nacelle. This is only used if the nacelle + model is used. + +.. inpfile:: actuator.air_density + + The air density. This is only used to compute the nacelle force. It should + match the density being used in both Nalu and OpenFAST. + +.. inpfile:: actuator.epsilon + + The spreading width :math:`\epsilon` in the Gaussian spreading function in + the `[chordwise, thickness, spanwise]` coordinate system to spread the + forces from the actuator point to the nodes. + In the case of the actuator disk, only the first value in the chordwise + direction is used for the uniform isotropic Gaussian. + +.. inpfile:: actuator.epsilon_chord + + This is the ratio :math:`\epsilon/c` in every direction + `[chordwise, thickness, spanwise]`. If this option is + specified, the code will choose a value of :math:`\epsilon` at every + location that + is :math:`c * \epsilon/c`. To avoid numerical instabilities, + the code will choose the maximum value between :math:`c * \epsilon/c` + and the value of ``actuator.epsilon_min`` specified. + +.. inpfile:: actuator.epsilon_min + + This is the minimum value of :math:`\epsilon` in the Gaussian spreading + function in the `[chordwise, thickness, spanwise]` coordinate system + to spread the forces from the actuator point to the nodes. + This option is required if the option ``actuator.epsilon_chord`` + is specified. + +.. inpfile:: actuator.epsilon_tower + + The spreading width :math:`\epsilon` in the Gaussian spreading function in + the inertial `[x, y, z]` reference frame. + If this value is not speficied, then ``actuator.epsilon`` or + ``actuator.epsilon_min`` will be used. + +.. inpfile:: actuator.restart_filename + + The checkpoint file for this turbine when restarting a simulation + +.. inpfile:: actuator.FAST_input_filename + + The FAST input file for this turbine + +.. inpfile:: actuator.turb_id + + A unique turbine id for each turbine + +.. inpfile:: actuator.num_swept_pts + + This is an optional parameter specifically for actuator disks. + This parameter determines the number of points that are placed azimuthally + between the actuator lines and spread the forcing over the disk's area. + When ``num_swept_pts`` is included the number of azimuthal points between the + lines is forced to this value at all radial locations. If ``num_swept_pts`` + is omitted then the azimuthal sampling is computed automatically with + different sampling at each radial location such that the average distance + between points matches the radial spacing. Fluid-Structure Interaction ``````````````````````````` @@ -1447,7 +1642,7 @@ Turbulence averaging .. note:: - The variable in the :inpfile:`turbulence_averaging` subsection are + The variable in the `turbulence_averaging` subsection are prefixed with ``turbulence_averaging.name`` but only the variable name after the period should appear in the input file. @@ -1631,7 +1826,7 @@ Data probes .. note:: - The variable in the :inpfile:`data_probes` subsection are prefixed + The variable in the `data_probes` subsection are prefixed with ``data_probes.name`` but only the variable name after the period should appear in the input file. @@ -1909,7 +2104,7 @@ Post-processing .. note:: - The variable in the :inpfile:`post_processing` subsection are prefixed with + The variable in the `post_processing` subsection are prefixed with ``post_processing.name`` but only the variable name after the period should appear in the input file. @@ -1955,7 +2150,159 @@ Post-processing .. _nalu_inp_transfers: -.. include:: ./abl_forcing.rst +ABL Forcing +``````````` + +.. inpfile:: abl_forcing + + ``abl_forcing`` allows the user to specify desired velocities + and temperatures at different heights. + These velocities and temperatures are enforced through the + use of source in the momentum and enthalpy equations. + The ``abl_forcing`` option needs to be specified in the + ``momentum`` and/or ``enthalpy`` source blocks: + + .. code-block:: yaml + + - source_terms: + momentum: abl_forcing + enthalpy: abl_forcing + + This option allows the code to implement source terms + in the momentum and/or enthalpy equations. + A sample + section is shown below + + .. code-block:: yaml + + abl_forcing: + search_method: stk_kdtree + search_tolerance: 0.0001 + search_expansion_factor: 1.5 + output_frequency: 1 + + from_target_part: [fluid_part] + + momentum: + type: computed + relaxation_factor: 1.0 + heights: [250.0, 500.0, 750.0] + target_part_format: "zplane_%06.1f" + + # The velocities at each plane + # Each list include a time and the velocities for each plane + # Notice that the total number of elements in each list will be + # number of planes + 1 + velocity_x: + - [0.0, 10.0, 5.0, 15.0] + - [100000.0, 10.0, 5.0, 15.0] + + velocity_y: + - [0.0, 0.0, 0.0, 0.0] + - [100000.0, 0.0, 0.0, 0.0] + + velocity_z: + - [0.0, 0.0, 0.0, 0.0] + - [100000.0, 0.0, 0.0, 0.0] + + temperature: + type: computed + relaxation_factor: 1.0 + heights: [250.0, 500.0, 750.0] + target_part_format: "zplane_%06.1f" + + temperature: + - [0.0, 300.0, 280.0, 310.0] + - [100000.0, 300.0, 280.0, 310.0] +.. note:: + + The variables in the `abl_forcing` subsection are + prefixed with ``abl_forcing.name`` but only the variable + name after the period should appear in the input file. + +.. inpfile:: abl_forcing.search_method + + This specifies the search method algorithm within the + stk framework. The default option `stk_kdtree` is recommended. + +.. inpfile:: abl_forcing.search_tolerance + + This is the tolerance specified for the + `search_method` algorithm. A default value of 0.0001 is recommended. + +.. inpfile:: abl_forcing.search_expansion_factor + + This option is related to the stk search algorithm. + A value of 1.5 is recommended. + +.. inpfile:: abl_forcing.output_frequency + + This is the frequency at which the source term is written + to the output value. A value of 1 means the source term + will be written to the output file every time-step. + +.. note:: + + There are now two options in the following inputs. + The can be ``momentum`` and/or ``temperature``. + +.. inpfile:: abl_forcing.momentum.computed + + This option allows the user to choose if a momentum source is computed + from a desired velocity (``computed``) or if a user defined + source term is directly + applied into the momentum equation (``user_defined``). + +.. inpfile:: abl_forcing.momentum.relaxation_factor + + This is a relaxation factor which can be used to under/over-relax + the momentum source term. + The default value is 1. + +.. inpfile:: abl_forcing.momentum.heights + + This is a list containing the planes at which the forcing should + be implemented. Each input is the height for that plane. + This is the naming convention in the mesh file. + +.. inpfile:: abl_forcing.momentum.target_part_format + + This is the format in which the planes are saved in the + mesh file. + +.. inpfile:: abl_forcing.momentum.velocity_x + + A set of lists containing the time in the first element, + followed by the desired velocity at each plane in the + :math:`x` direction. + +.. inpfile:: abl_forcing.momentum.velocity_y + + A set of lists containing the time in the first element, + followed by the desired velocity at each plane in the + :math:`y` direction. + + +.. inpfile:: abl_forcing.momentum.velocity_z + + A set of lists containing the time in the first element, + followed by the desired velocity at each plane in the + :math:`z` direction. + +.. note:: + + The temperature has the same inputs as the momentum source + (``abl_forcing.temperature.type``, + ``abl_forcing.temperature.relaxation_factor``, + ``abl_forcing.temperature.heights``, and + ``abl_forcing.temperature.target_part_format``) + which take the same options. + +.. inpfile:: abl_forcing.temperature.temperature + + A set of lists containing the time in the first element, + followed by the desired temperature at each plane. + Boundary Layer Statistics ````````````````````````` @@ -2048,7 +2395,7 @@ Boundary Layer Statistics Larger values of ``height_multiplier`` allow a higher precision to be used in determining the unique heights and better behavior in some meshes. - [*Optional*, default value: ``1.0e6``] + [*Optional*, default value: ``2.0e6``] Transfers @@ -2057,7 +2404,7 @@ Transfers .. inpfile:: transfers Transfers section describes the search and mapping operations to be performed - between participating :inpfile:`realms` within a simulation. + between participating `realms` within a simulation. Simulations ----------- @@ -2065,3 +2412,5 @@ Simulations .. inpfile:: simulations This is the top-level section that orchestrates the entire execution of Nalu-Wind. + + diff --git a/docs/sphinx/source/user/nalu_run/turbine_modeling.rst b/docs/sphinx/source/user/nalu_run/turbine_modeling.rst deleted file mode 100644 index 593c9cd61..000000000 --- a/docs/sphinx/source/user/nalu_run/turbine_modeling.rst +++ /dev/null @@ -1,196 +0,0 @@ -Actuator Turbine Model -`````````````````````` - -.. inpfile:: actuator - - ``actuator`` subsection defines the inputs for actuator line simulations. A - sample section is shown below for running actuator line simulations - coupled to OpenFAST with two turbines. - -.. code-block:: yaml - - actuator: - type: ActLineFAST - search_method: stk_kdtree - search_target_part: Unspecified-2-HEX - - n_turbines_glob: 2 - dry_run: False - debug: False - t_start: 0.0 - simStart: init # init/trueRestart/restartDriverInitFAST - t_max: 5.0 - n_every_checkpoint: 100 - - Turbine0: - procNo: 0 - num_force_pts_blade: 50 - num_force_pts_tower: 20 - nacelle_cd: 1.0 - nacelle_area: 1.0 - air_density: 1.225 - epsilon: [ 5.0, 5.0, 5.0 ] - turbine_base_pos: [ 0.0, 0.0, -90.0 ] - turbine_hub_pos: [ 0.0, 0.0, 0.0 ] - restart_filename: "" - FAST_input_filename: "Test01.fst" - turb_id: 1 - turbine_name: machine_zero - - Turbine1: - procNo: 0 - num_force_pts_blade: 50 - num_force_pts_tower: 20 - nacelle_cd: 1.0 - nacelle_area: 1.0 - air_density: 1.225 - epsilon: [ 5.0, 5.0, 5.0 ] - turbine_base_pos: [ 250.0, 0.0, -90.0 ] - turbine_hub_pos: [ 250.0, 0.0, 0.0 ] - restart_filename: "" - FAST_input_filename: "Test02.fst" - turb_id: 2 - turbine_name: machine_one - - -.. inpfile:: actuator.type - - Type of actuator source. Options are ``ActLineFAST`` and ``ActDiskFAST``. ``ActLineFAST`` is for actuator lines, and ``ActDiskFAST`` is for actuator disks. The actuator disk uses a stationary actuator line model to compute forces at the blade locations and then the average force of the blades is spread azimuthally between the blades sampling points. - -.. inpfile:: actuator.search_method - - String specifying the type of search method used to identify the nodes within the search radius of the actuator points. The only valid option is ``stk_kdtree``. The ``boost_rtree`` option has been deprecated by the STK search library. - -.. inpfile:: search_target_part - - String or an array of strings specifying the parts of the mesh to be searched to identify the nodes near the actuator points. - -.. inpfile:: actuator.n_turbines_glob - - Total number of turbines in the simulation. The input file must contain a number of turbine specific sections (`Turbine0`, `Turbine1`, ..., `Turbine(n-1)`) that is consistent with `nTurbinesGlob`. - -.. inpfile:: actuator.debug - - Enable debug outputs if set to true - -.. inpfile:: actuator.dry_run - - The simulation will not run if dryRun is set to true. However, the simulation will read the input files, allocate turbines to processors and prepare to run the individual turbine instances. This flag is useful to test the setup of the simulation before running it. - -.. inpfile:: actuator.simStart - - Flag indicating whether the simulation starts from scratch or restart. ``simStart`` takes on one of three values: - - * ``init`` - Use this option when starting a simulation from `t=0s`. - * ``trueRestart`` - While OpenFAST allows for restart of a turbine simulation, external components like the Bladed style controller may not. Use this option when all components of the simulation are known to restart. - * ``restartDriverInitFAST`` - When the ``restartDriverInitFAST`` option is selected, the individual turbine models start from `t=0s` and run up to the specified restart time using the inflow data stored at the actuator nodes from a hdf5 file. The C++ API stores the inflow data at the actuator nodes in a hdf5 file at every OpenFAST time step and then reads it back when using this restart option. This restart option is especially useful when the glue code is a CFD solver. - -.. inpfile:: actuator.t_start - - Start time of the simulation - -.. inpfile:: actuator.t_end - - End time of the simulation. ``t_end`` <= ``t_max`` - -.. inpfile:: actuator.t_max - - Max time of the simulation - - -.. note:: - - ``t_max`` can only be set when OpenFAST is running from `t=0s` and ``simStart`` is ``init``. ``t_max`` can not be changed on a restart. OpenFAST will not be able to run beyond ``t_max``. Choose ``t_max`` to be large enough to accomodate any possible future extensions of runs. One can change ``t_start`` and ``t_end`` to start and stop the simulation any number of times as long as ``t_end`` <= ``t_max``. - -.. inpfile:: actuator.dt_fast - - Time step for OpenFAST. All turbines should have the same time step. - -.. inpfile:: actuator.n_every_checkpoint - - Restart files will be written every so many time steps - -**Turbine specific input options** - -.. inpfile:: actuator.turbine_base_pos - - The position of the turbine base for actuator-line/disk simulations - -.. inpfile:: actuator.num_force_pts_blade - - The number of actuator points along each blade for actuator-line/disk simulations - -.. inpfile:: actuator.num_force_pts_tower - - The number of actuator points along the tower for actuator-line/disk simulations. - -.. inpfile:: actuator.nacelle_cd - - The drag coefficient for the nacelle. If this is set to zero, or not - defined, the code will not implement the nacelle model. - -.. inpfile:: actuator.nacelle_area - - The reference area for the nacelle. This is only used if the nacelle - model is used. - -.. inpfile:: actuator.air_density - - The air density. This is only used to compute the nacelle force. It should - match the density being used in both Nalu and OpenFAST. - -.. inpfile:: actuator.epsilon - - The spreading width :math:`\epsilon` in the Gaussian spreading function in - the `[chordwise, thickness, spanwise]` coordinate system to spread the - forces from the actuator point to the nodes. - In the case of the actuator disk, only the first value in the chordwise - direction is used for the uniform isotropic Gaussian. - -.. inpfile:: actuator.epsilon_chord - - This is the ratio :math:`\epsilon/c` in every direction - `[chordwise, thickness, spanwise]`. If this option is - specified, the code will choose a value of :math:`\epsilon` at every - location that - is :math:`c * \epsilon/c`. To avoid numerical instabilities, - the code will choose the maximum value between :math:`c * \epsilon/c` - and the value of ``actuator.epsilon_min`` specified. - -.. inpfile:: actuator.epsilon_min - - This is the minimum value of :math:`\epsilon` in the Gaussian spreading - function in the `[chordwise, thickness, spanwise]` coordinate system - to spread the forces from the actuator point to the nodes. - This option is required if the option ``actuator.epsilon_chord`` - is specified. - -.. inpfile:: actuator.epsilon_tower - - The spreading width :math:`\epsilon` in the Gaussian spreading function in - the inertial `[x, y, z]` reference frame. - If this value is not speficied, then ``actuator.epsilon`` or - ``actuator.epsilon_min`` will be used. - -.. inpfile:: actuator.restart_filename - - The checkpoint file for this turbine when restarting a simulation - -.. inpfile:: actuator.FAST_input_filename - - The FAST input file for this turbine - -.. inpfile:: actuator.turb_id - - A unique turbine id for each turbine - -.. inpfile:: actuator.num_swept_pts - - This is an optional parameter specifically for actuator disks. - This parameter determines the number of points that are placed azimuthally - between the actuator lines and spread the forcing over the disk's area. - When ``num_swept_pts`` is included the number of azimuthal points between the - lines is forced to this value at all radial locations. If ``num_swept_pts`` - is omitted then the azimuthal sampling is computed automatically with - different sampling at each radial location such that the average distance - between points matches the radial spacing. diff --git a/docs/sphinx/source/verification/verification.rst b/docs/sphinx/source/verification/verification.rst index 7a317cb8c..b2c586ac6 100644 --- a/docs/sphinx/source/verification/verification.rst +++ b/docs/sphinx/source/verification/verification.rst @@ -442,17 +442,19 @@ Figure :numref:`laplace-ncoc-b`. .. _linear-patch: -+---------------+---------------------+---------------+---------------+ -| dof | :math:`L_{\infty}` | L1 | L2 | -+===============+=====================+===============+===============+ -| temperature | 3.33067e-16 | 2.30077e-17 | 4.68103e-17 | -+---------------+---------------------+---------------+---------------+ -| dTdx | 4.13225e-13 | 9.06848e-15 | 1.98249e-14 | -+---------------+---------------------+---------------+---------------+ -| dTdy | 4.15668e-13 | 1.11256e-14 | 2.15065e-14 | -+---------------+---------------------+---------------+---------------+ -| dTdz | 4.31211e-13 | 9.60785e-15 | 1.97517e-14 | -+---------------+---------------------+---------------+---------------+ +.. table:: Patch test + + +---------------+---------------------+---------------+---------------+ + | dof | :math:`L_{\infty}` | L1 | L2 | + +===============+=====================+===============+===============+ + | temperature | 3.33067e-16 | 2.30077e-17 | 4.68103e-17 | + +---------------+---------------------+---------------+---------------+ + | dTdx | 4.13225e-13 | 9.06848e-15 | 1.98249e-14 | + +---------------+---------------------+---------------+---------------+ + | dTdy | 4.15668e-13 | 1.11256e-14 | 2.15065e-14 | + +---------------+---------------------+---------------+---------------+ + | dTdz | 4.31211e-13 | 9.60785e-15 | 1.97517e-14 | + +---------------+---------------------+---------------+---------------+ Given the order of accuracy results for the P1 implementation, a linear patch test was run. The temperature solution was simply,