docs: Move table titles from CompleteXMLSchema.rst to corresponding include file (#3321)

* alter SchemaToRSTDocumentation to move headers into table files

* rename Element to XML Element

* avoid includeding headers in table files when included outside of CompleteXMLSchema.rst

---------

Co-authored-by: Randolph R. Settgast <settgast1@llnl.gov>

Author: ryar9534

scripts/SchemaToRSTDocumentation.py

@@ -13,7 +13,10 @@ def comment(self, data):
         self.end(etree.Comment)
 
 
-def writeTableRST(file_name, values):
+def writeTableRST(type_name, file_name, title_prefix, values):
+
+    element_header = '%s: %s' % (title_prefix, type_name)
+
     L = [[len(x) for x in row] for row in values]
 
     # np isn't in the docker images for our CI
@@ -54,7 +57,9 @@ def writeTableRST(file_name, values):
 
     # Build table
     with open(file_name, 'w') as f:
-        f.write('\n\n')
+        f.write('%s\n' % (element_header))
+        f.write('=' * len(element_header) + '\n')
+        f.write('\n')
         f.write(boundary)
         f.write(formatted_lines[0])
         f.write(boundary)
@@ -269,13 +274,10 @@ def main(schema_name='schema.xsd', output_folder='./', xsd='{http://www.w3.org/2
         for type_name in sorted(input_attribute_map.keys()):
             # Write the individual tables
             table_values = buildTableValues(input_attribute_map[type_name])
-            writeTableRST('%s/%s.rst' % (datastructure_folder, type_name), table_values)
+            writeTableRST( type_name, '%s/%s.rst' % (datastructure_folder, type_name), 'XML Element', table_values)
 
             # Write to the master list
-            element_header = 'Element: %s' % (type_name)
             output_handle.write('\n.. _XML_%s:\n\n' % (type_name))
-            output_handle.write('%s\n' % (element_header))
-            output_handle.write('=' * len(element_header) + '\n')
             output_handle.write('.. include:: %s.rst\n\n' % (type_name))
 
         # Parse the non-input schema definitions
@@ -288,13 +290,10 @@ def main(schema_name='schema.xsd', output_folder='./', xsd='{http://www.w3.org/2
             table_values = buildTableValues(other_attribute_map[type_name],
                                             link_string='DATASTRUCTURE',
                                             include_defaults=False)
-            writeTableRST('%s/%s_other.rst' % (datastructure_folder, type_name), table_values)
+            writeTableRST( type_name, '%s/%s_other.rst' % (datastructure_folder, type_name), 'Datastructure', table_values)
 
             # Write to the master list
-            element_header = 'Datastructure: %s' % (type_name)
             output_handle.write('\n.. _DATASTRUCTURE_%s:\n\n' % (type_name))
-            output_handle.write('%s\n' % (element_header))
-            output_handle.write('=' * len(element_header) + '\n')
             output_handle.write('.. include:: %s_other.rst\n\n' % (type_name))
 
 

src/coreComponents/events/docs/EventManager.rst

@@ -53,7 +53,7 @@ Event
 The children of the Event block define the events that may execute during a simulation.  These may be of type ``HaltEvent``, ``PeriodicEvent``, or ``SoloEvent``.  The exit criteria for the global event loop are defined by the attributes ``maxTime`` and ``maxCycle`` (which by default are set to their max values).  If the optional logLevel flag is set, the EventManager will report additional information with regards to timestep requests and event forecasts for its children.
 
 .. include:: /docs/sphinx/datastructure/Events.rst
-
+    :start-line: 3
 
 PeriodicEvent
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -68,20 +68,21 @@ By default, a PeriodicEvent will execute throughout the entire simulation.  This
 The timestep request event is typically determined via its target.  However, this value can be overridden by setting the ``forceDt`` or ``maxEventDt`` attributes.
 
 .. include:: /docs/sphinx/datastructure/PeriodicEvent.rst
-
+    :start-line: 3
 
 SoloEvent
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 This type of event will execute once once the event loop reaches a certain cycle (targetCycle) or time (targetTime).  Similar to the PeriodicEvent type, this event will modify its timestep requests so that a cycle occurs at the exact time requested (this can be turned off by specifying targetExactTimestep="0").  The forecast calculations follow an similar approach to the PeriodicEvent type.
 
 .. include:: /docs/sphinx/datastructure/SoloEvent.rst
-
+    :start-line: 3
 
 HaltEvent
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 This event type is designed to track the wall clock.  When the time exceeds the value specified via maxRunTime, the event will trigger and set a flag that instructs the main EventManager loop to cleanly exit at the end of the current cycle.  The event for cast for this event type is given by: ``forecast = (maxRuntime - (currentTime - startTime)) / realDt``
 
 .. include:: /docs/sphinx/datastructure/HaltEvent.rst
+    :start-line: 3
 
 
 

src/coreComponents/events/docs/TasksManager.rst

@@ -22,12 +22,14 @@ Task
 The children of the Tasks block define different Tasks to be triggered by events specified in the :ref:`EventManager` during the execution of the simulation. At present the only supported task is the ``PackCollection`` used to collect time history data for output by a TimeHistory output.
 
 .. include:: /docs/sphinx/datastructure/Tasks.rst
-
+    :start-line: 3
+    
 PackCollection
 ***************************
 The ``PackCollection`` Task is used to collect time history information from fields. Either the entire field or specified named sets of indices in the field can be collected.
 
 .. include:: /docs/sphinx/datastructure/PackCollection.rst
+    :start-line: 3
 
 Note: The time history information collected via this task is buffered internally until it is output by a linked TimeHistory Output.
 

src/coreComponents/functions/docs/FunctionManager.rst

@@ -65,7 +65,7 @@ A table function uses a set of pre-computed values defined at points on a struct
 Typically, the axes of the table will represent time and/or spatial dimensions; however, these can be applied to represent phase diagrams, etc.
 
 .. include:: /docs/sphinx/datastructure/TableFunction.rst
-
+    :start-line: 3
 
 1D Table
 *************
@@ -158,6 +158,7 @@ This function leverages the symbolic expression library mathpresso to define and
 These functions are processed using an x86-64 JIT compiler, so are nearly as efficient as natively compiled C++ expressions.
 
 .. include:: /docs/sphinx/datastructure/SymbolicFunction.rst
+    :start-line: 3
 
 The ``variableNames`` attribute defines a set of single-character names for the inputs to the symbolic function.
 There should be a definition for each scalar input and for each component of a vector input.
@@ -188,7 +189,7 @@ This function is derived from the symbolic function.
 However, instead of using the time or object as inputs, it is used to combine the outputs of other functions using a symbolic expression.
 
 .. include:: /docs/sphinx/datastructure/CompositeFunction.rst
-
+    :start-line: 3
 
 The ``functionNames`` attribute defines the set of input functions to use (these may be of any type, and may each have any number of inputs).
 The ``variableNames`` attribute defines a set of single-character names for each function.

src/coreComponents/physicsSolvers/fluidFlow/SourceFluxStatistics.cpp

@@ -31,7 +31,7 @@ SourceFluxStatsAggregator::SourceFluxStatsAggregator( const string & name,
                                                       Group * const parent ):
   Base( name, parent )
 {
-  getWrapper< integer >( Group::viewKeyStruct::logLevelString() ).
+  getWrapperBase( Group::viewKeyStruct::logLevelString() ).
     appendDescription( GEOS_FMT( "\n- Log Level 1 outputs the sum of all {0}(s) produced rate & mass,\n"
                                  "- Log Level 2 details values for each {0},\n"
                                  "- Log Level 3 details values for each region.",

src/coreComponents/schema/schema.xsd

@@ -1770,6 +1770,10 @@ stress - traction is applied to the faces as specified by the inner product of i
 		</xsd:restriction>
 	</xsd:simpleType>
 	<xsd:complexType name="LinearSolverParametersType">
+		<!--adaptiveExponent => Exponent parameter for adaptive method-->
+		<xsd:attribute name="adaptiveExponent" type="real64" default="1" />
+		<!--adaptiveGamma => Gamma parameter for adaptive method-->
+		<xsd:attribute name="adaptiveGamma" type="real64" default="0.1" />
 		<!--amgAggressiveCoarseningLevels => AMG number of levels for aggressive coarsening-->
 		<xsd:attribute name="amgAggressiveCoarseningLevels" type="integer" default="0" />
 		<!--amgAggressiveCoarseningPaths => AMG number of paths for aggressive coarsening-->
@@ -1822,6 +1826,8 @@ stress - traction is applied to the faces as specified by the inner product of i
 		<xsd:attribute name="krylovMaxIter" type="integer" default="200" />
 		<!--krylovMaxRestart => Maximum iterations before restart (GMRES only)-->
 		<xsd:attribute name="krylovMaxRestart" type="integer" default="200" />
+		<!--krylovStrongestTol => Strongest-allowed tolerance for adaptive method-->
+		<xsd:attribute name="krylovStrongestTol" type="real64" default="1e-08" />
 		<!--krylovTol => Relative convergence tolerance of the iterative method
 If the method converges, the iterative solution :math:`\mathsf{x}_k` is such that
 the relative residual norm satisfies:
@@ -1900,7 +1906,7 @@ the relative residual norm satisfies:
 		<!--lineSearchAction => How the line search is to be used. Options are: 
  * None    - Do not use line search.
 * Attempt - Use line search. Allow exit from line search without achieving smaller residual than starting residual.
-* Require - Use line search. If smaller residual than starting resdual is not achieved, cut time step.-->
+* Require - Use line search. If smaller residual than starting resdual is not achieved, cut time-step.-->
 		<xsd:attribute name="lineSearchAction" type="geos_NonlinearSolverParameters_LineSearchAction" default="Attempt" />
 		<!--lineSearchCutFactor => Line search cut factor. For instance, a value of 0.5 will result in the effective application of the last solution by a factor of (0.5, 0.25, 0.125, ...)-->
 		<xsd:attribute name="lineSearchCutFactor" type="real64" default="0.5" />
@@ -1922,10 +1928,12 @@ the relative residual norm satisfies:
 		<xsd:attribute name="maxNumConfigurationAttempts" type="integer" default="10" />
 		<!--maxSubSteps => Maximum number of time sub-steps allowed for the solver-->
 		<xsd:attribute name="maxSubSteps" type="integer" default="10" />
-		<!--maxTimeStepCuts => Max number of time step cuts-->
+		<!--maxTimeStepCuts => Max number of time-step cuts-->
 		<xsd:attribute name="maxTimeStepCuts" type="integer" default="2" />
 		<!--minNormalizer => Value used to make sure that residual normalizers are not too small when computing residual norm.-->
 		<xsd:attribute name="minNormalizer" type="real64" default="1e-12" />
+		<!--minTimeStepIncreaseInterval => Minimum number of cycles since the last time-step cut for increasing the time-step again.-->
+		<xsd:attribute name="minTimeStepIncreaseInterval" type="integer" default="10" />
 		<!--newtonMaxIter => Maximum number of iterations that are allowed in a Newton loop.-->
 		<xsd:attribute name="newtonMaxIter" type="integer" default="5" />
 		<!--newtonMinIter => Minimum number of iterations that are required before exiting the Newton loop.-->
@@ -1941,15 +1949,15 @@ the relative residual norm satisfies:
 		<xsd:attribute name="sequentialConvergenceCriterion" type="geos_NonlinearSolverParameters_SequentialConvergenceCriterion" default="ResidualNorm" />
 		<!--subcycling => Flag to decide whether to iterate between sequentially coupled solvers or not.-->
 		<xsd:attribute name="subcycling" type="integer" default="0" />
-		<!--timeStepCutFactor => Factor by which the time step will be cut if a timestep cut is required.-->
+		<!--timeStepCutFactor => Factor by which the time-step will be cut if a time-step cut is required.-->
 		<xsd:attribute name="timeStepCutFactor" type="real64" default="0.5" />
-		<!--timeStepDecreaseFactor => Factor by which the time step is decreased when the number of Newton iterations is large.-->
+		<!--timeStepDecreaseFactor => Factor by which the time-step is decreased when the number of Newton iterations is large.-->
 		<xsd:attribute name="timeStepDecreaseFactor" type="real64" default="0.5" />
-		<!--timeStepDecreaseIterLimit => Fraction of the max Newton iterations above which the solver asks for the time-step to be decreased for the next time step.-->
+		<!--timeStepDecreaseIterLimit => Fraction of the max Newton iterations above which the solver asks for the time-step to be decreased for the next time-step.-->
 		<xsd:attribute name="timeStepDecreaseIterLimit" type="real64" default="0.7" />
-		<!--timeStepIncreaseFactor => Factor by which the time step is increased when the number of Newton iterations is small.-->
+		<!--timeStepIncreaseFactor => Factor by which the time-step is increased when the number of Newton iterations is small.-->
 		<xsd:attribute name="timeStepIncreaseFactor" type="real64" default="2" />
-		<!--timeStepIncreaseIterLimit => Fraction of the max Newton iterations below which the solver asks for the time-step to be increased for the next time step.-->
+		<!--timeStepIncreaseIterLimit => Fraction of the max Newton iterations below which the solver asks for the time-step to be increased for the next time-step.-->
 		<xsd:attribute name="timeStepIncreaseIterLimit" type="real64" default="0.4" />
 		<!--normType => Norm used by the flow solver to check nonlinear convergence. Valid options:
 * Linfinity
@@ -2938,7 +2946,7 @@ Equal to 1 for surface conditions, and to 0 for reservoir conditions-->
 		<!--maxNumResolves => Value to indicate how many resolves may be executed to perform surface generation after the execution of flow and mechanics solver. -->
 		<xsd:attribute name="maxNumResolves" type="integer" default="10" />
 		<!--newFractureInitializationType => Type of new fracture element initialization. Can be Pressure or Displacement. -->
-		<xsd:attribute name="newFractureInitializationType" type="geos_HydrofractureSolver_lt_geos_SinglePhasePoromechanics_lt_geos_SinglePhaseBase_cm_-geos_SolidMechanicsLagrangianFEM_gt_-_gt__InitializationType" default="Pressure" />
+		<xsd:attribute name="newFractureInitializationType" type="geos_HydrofractureSolver_lt_geos_SinglePhasePoromechanics_lt_geos_SinglePhaseBase_cm_-geos_SolidMechanicsLagrangianFEM_gt__gt__InitializationType" default="Pressure" />
 		<!--solidSolverName => Name of the solid solver used by the coupled solver-->
 		<xsd:attribute name="solidSolverName" type="groupNameRef" use="required" />
 		<!--stabilizationMultiplier => Constant multiplier of stabilization strength-->
@@ -2961,7 +2969,7 @@ Local- Add jump stabilization on interior of macro elements-->
 		<!--name => A name is required for any non-unique nodes-->
 		<xsd:attribute name="name" type="groupName" use="required" />
 	</xsd:complexType>
-	<xsd:simpleType name="geos_HydrofractureSolver_lt_geos_SinglePhasePoromechanics_lt_geos_SinglePhaseBase_cm_-geos_SolidMechanicsLagrangianFEM_gt_-_gt__InitializationType">
+	<xsd:simpleType name="geos_HydrofractureSolver_lt_geos_SinglePhasePoromechanics_lt_geos_SinglePhaseBase_cm_-geos_SolidMechanicsLagrangianFEM_gt__gt__InitializationType">
 		<xsd:restriction base="xsd:string">
 			<xsd:pattern value=".*[\[\]`$].*|Pressure|Displacement" />
 		</xsd:restriction>