Squashed commit of the following:

commit c058c08
Author: ttruster <timothy.truster@gmail.com>
Date:   Wed Nov 30 13:23:01 2022 -0500

    Start revising the documentation
    finished most of index for kernel, constraint, scalar

commit 5348aa5
Author: ttruster <timothy.truster@gmail.com>
Date:   Wed Nov 30 13:20:06 2022 -0500

    Allow for 1d/2d/3d scalar for periodic conditions
    Fix a typo

commit 3afaf21
Merge: 06c2d09 a77fef9
Author: ttruster <timothy.truster@gmail.com>
Date:   Mon Nov 14 23:57:28 2022 -0500

    Clean up some tests
    remove parameter from Mortar base
    Add flags to compute only rows of R and J
    Add tensor mechanics case to check the row assembly
    Verify that tests run correctly

commit a77fef9
Merge: 54f3d3a 094bc01
Author: ttruster <timothy.truster@gmail.com>
Date:   Fri Nov 11 16:42:38 2022 -0500

    Merge pull request #2 from lindsayad/mortar-scalar-assembly

    Simplify residual object code

commit 094bc01
Author: Alex Lindsay <alexlindsay239@gmail.com>
Date:   Fri Nov 11 12:48:50 2022 -0800

    Simplify residual object code

    Make it so that residual objects residuals and Jacobian routines
    don't have to be interwoven with pound defines

commit aa6ce99
Author: Alex Lindsay <alexlindsay239@gmail.com>
Date:   Fri Nov 11 12:39:41 2022 -0800

    Revert "Add error check for non-sparse AD"

    This reverts commit 0b46030.

commit b285c69
Author: Alex Lindsay <alexlindsay239@gmail.com>
Date:   Fri Nov 11 12:39:30 2022 -0800

    Revert "Add other error checks to see if that works."

    This reverts commit b4dd527.

commit 06c2d09
Author: ttruster <timothy.truster@gmail.com>
Date:   Mon Nov 14 23:51:43 2022 -0500

    Clean up some tests
    remove parameter from Mortar base
    Add flags to compute only rows of R and J
    Add tensor mechanics case to check the row assembly
    Verify that tests run correctly

commit 54f3d3a
Author: ttruster <timothy.truster@gmail.com>
Date:   Fri Nov 11 14:55:56 2022 -0500

    Add other error checks to see if that works.

commit 309881a
Author: ttruster <timothy.truster@gmail.com>
Date:   Fri Nov 11 00:21:15 2022 -0500

    Add error check for non-sparse AD

commit 1f5ccd4
Merge: b3cbe43 b4017b3
Author: ttruster <timothy.truster@gmail.com>
Date:   Thu Nov 10 23:53:55 2022 -0500

    Merge pull request #1 from lindsayad/mortar-scalar-assembly

    Make residual-and-Jacobian separate work and test

commit b4017b3
Author: Alex Lindsay <alexlindsay239@gmail.com>
Date:   Thu Nov 10 18:28:02 2022 -0800

    Make residual-and-Jacobian separate work and test

commit b3cbe43
Author: ttruster <timothy.truster@gmail.com>
Date:   Thu Nov 10 23:39:07 2022 -0500

    Add separate assembly case for two scalar variables
    Add a bunch more comments to document which terms are done where
    Verified with test case

commit cfd5462
Author: ttruster <timothy.truster@gmail.com>
Date:   Wed Nov 9 15:19:55 2022 -0500

    Move test sources back to test app instead of module

commit 9528cb5
Author: ttruster <timothy.truster@gmail.com>
Date:   Wed Nov 9 00:07:42 2022 -0500

    Fix error of missing () in residual integration loop
    Add test cases and gold files for the 2d homogenization

commit 33ae53e
Author: ttruster <timothy.truster@gmail.com>
Date:   Sun Nov 6 01:04:19 2022 -0500

    Now the code compiles but doesn't converge yet

commit 0d1942c
Author: ttruster <timothy.truster@gmail.com>
Date:   Sun Nov 6 00:45:23 2022 -0400

    First attempt at making elasticity kernel test with scalars.
    Fails to link with 'thunk' errors.

framework/doc/content/source/constraints/MortarScalarBase.md

@@ -0,0 +1,16 @@
+# MortarScalarBase
+
+describe the parameters like the kernel system
+say what loops are added, primary and other scalars
+
+The `MortarScalarBase` is the automatic differentiation version of [`PenaltyPeriodicSegmentalConstraint`](PenaltyPeriodicSegmentalConstraint.md).
+
+Mention AD version provided, and with warning for global only.
+
+!syntax description /Constraints/MortarScalarBase
+
+!syntax parameters /Constraints/MortarScalarBase
+
+!syntax inputs /Constraints/MortarScalarBase
+
+!syntax children /Constraints/MortarScalarBase

framework/doc/content/source/constraints/PenaltyPeriodicSegmentalConstraint.md

@@ -1,19 +1,22 @@
 # PenaltyPeriodicSegmentalConstraint
 
-The `PenaltyPeriodicSegmentalConstraint` a periodic boundary condition between a microscale and 
+Add the paper reference
+add a weak form term
+
+The `PenaltyPeriodicSegmentalConstraint` a periodic boundary condition between a microscale and
 macroscale field. Coupling is made between a scalar macro-gradient variable and the concentration field within
 the periodic domain. Only the macro to micro coupling terms are handled here. The micro-micro coupling terms
-are handled using the [PenaltyEqualValueConstraint](/PenaltyEqualValueConstraint.md) applied to the same 
+are handled using the [PenaltyEqualValueConstraint](/PenaltyEqualValueConstraint.md) applied to the same
 primary/secondary pair.
 
 The applied macroscale conjugate gradient is applied as `kappa_aux` vector as an auxillary
 scalar. The computed macroscale gradient `kappa` is equal to this value for isotropic-unitary
 diffusivity. The volume integral of the gradient of the primary field will be equal to these
 imposed values.
 
-The microscale variable is specified using the `primary_variable` parameter. 
+The microscale variable is specified using the `primary_variable` parameter.
 If the solution values to be matched are between different variables, the
-`secondary_variable` parameter can also be supplied. The enforcement takes place in a penalty sense, 
+`secondary_variable` parameter can also be supplied. The enforcement takes place in a penalty sense,
 which eliminates the need to supply Lagrange multipliers.
 
 !listing test/tests/mortar/periodic_segmental_constraint/penalty_periodic_simple2d.i block=Constraints

framework/doc/content/source/constraints/PeriodicSegmentalConstraint.md

@@ -1,17 +1,20 @@
 # PeriodicSegmentalConstraint
 
-The `PeriodicSegmentalConstraint` a periodic boundary condition between a microscale and 
+Add the paper reference
+add a weak form term
+
+The `PeriodicSegmentalConstraint` a periodic boundary condition between a microscale and
 macroscale field. Coupling is made between a scalar macro-gradient variable and the concentration field within
 the periodic domain. Only the macro to micro coupling terms are handled here. The micro-micro coupling terms
-are handled using the [EqualValueConstraint](/EqualValueConstraint.md) applied to the same 
+are handled using the [EqualValueConstraint](/EqualValueConstraint.md) applied to the same
 primary/secondary pair.
 
 The applied macroscale conjugate gradient is applied as `kappa_aux` vector as an auxillary
 scalar. The computed macroscale gradient `kappa` is equal to this value for isotropic-unitary
 diffusivity. The volume integral of the gradient of the primary field will be equal to these
 imposed values.
 
-The microscale variable is specified using the `primary_variable` parameter. 
+The microscale variable is specified using the `primary_variable` parameter.
 If the solution values to be matched are between different variables, the
 `secondary_variable` parameter can also be supplied. The enforcement takes place using Lagrange multipliers.
 

framework/doc/content/source/kernels/ADScalarLMKernel.md

@@ -1,21 +1,6 @@
 # ADScalarLMKernel
 
-This Kernel implements part of the equation that enforces the constraint of
-
-\begin{equation}
- \int_{\Omega} \phi = V_0
-\end{equation}
-
-where $V_0$ is a given constant, using a Lagrange multiplier approach. The residual of $\phi$ related to the Lagrange multiplier is given as:
-
-\begin{equation}
-  F^{(\phi)}_i \equiv \lambda^h \int_{\Omega} \varphi_i \;\text{d}\Omega \label{eq:eq1}
-\end{equation}
-
-In particular, this Kernel implements the residual contribution from
-the $\lambda$ in [eq:eq1] , and their Jacobian contributions. See also [AverageValueConstraint.md] for the residual of the Lagrange multiplier variable.
-
-The detailed description of the derivation can be found at [scalar_constraint_kernel](https://github.com/idaholab/large_media/blob/master/framework/scalar_constraint_kernel.pdf).
+The `ADScalarLMKernel` is the automatic differentiation version of [`ScalarLMKernel`](ScalarLMKernel.md).
 
 !syntax parameters /Kernels/ADScalarLMKernel
 

framework/doc/content/source/kernels/KernelScalarBase.md

@@ -0,0 +1,28 @@
+# KernelScalarBase
+
+Mention AD version provided, and with warning for global only.
+describe the parameters like the kernel system
+say what loops are added, primary and other scalars
+
+This Kernel implements part of the equation that enforces the constraint of
+
+\begin{equation}
+ \int_{\Omega} \phi = V_0
+\end{equation}
+
+where $V_0$ is a given constant, using a Lagrange multiplier approach. The residual of $\phi$ related to the Lagrange multiplier is given as:
+
+\begin{equation}
+  F^{(\phi)}_i \equiv \lambda^h \int_{\Omega} \varphi_i \;\text{d}\Omega \label{eq:eq1}
+\end{equation}
+
+In particular, this Kernel implements the residual contribution from
+the $\lambda$ in [eq:eq1] , and their Jacobian contributions. See also [AverageValueConstraint.md] for the residual of the Lagrange multiplier variable.
+
+The detailed description of the derivation can be found at [scalar_constraint_kernel](https://github.com/idaholab/large_media/blob/master/framework/scalar_constraint_kernel.pdf).
+
+!syntax parameters /Kernels/KernelScalarBase
+
+!syntax inputs /Kernels/KernelScalarBase
+
+!syntax children /Kernels/KernelScalarBase

framework/doc/content/source/kernels/ScalarLMKernel.md

@@ -1,6 +1,6 @@
 # ScalarLMKernel
 
-This Kernel implements part of the equation that enforces the constraint of
+This Kernel implements all of the terms from the equation that enforces the constraint of
 
 \begin{equation}
  \int_{\Omega} \phi = V_0
@@ -12,6 +12,9 @@ where $V_0$ is a given constant, using a Lagrange multiplier approach. The resid
   F^{(\phi)}_i \equiv \lambda^h \int_{\Omega} \varphi_i \;\text{d}\Omega \label{eq:eq1}
 \end{equation}
 
+This kernel is an alternative to the combination of slmk, avc, and a user object. It shows how to derive from the scalar kernel base and assemble with a scalar variable.
+Currently, a Null Scalar Kernel is required to activate the dependency of the scalar variable within the block or subdomain of this object.
+
 In particular, this Kernel implements the residual contribution from
 the $\lambda$ in [eq:eq1] , and their Jacobian contributions. See also [AverageValueConstraint.md] for the residual of the Lagrange multiplier variable.
 

framework/doc/content/source/systems/NonlinearSystem.md

@@ -1,5 +1,7 @@
 # NonlinearSystem
 
+Useful for links and math, but otherwise don't add anything here
+
 The NonlinearSystem object holds the equation system created by the normal FEM process
 (e.g. the Matrix and RHS vector) to be solved. Normally MOOSE uses PETSc to store and
 solve this system. This object is where you will find the callback routines used
@@ -373,12 +375,12 @@ slowly.  To improve convergence, PETSc and other iterative solver packages
 apply a [preconditioner](https://en.wikipedia.org/wiki/Preconditioner) to the
 system of equations/sparse matrix before applying the iterative solver.
 
-A great number of preconditioners exist, but 
+A great number of preconditioners exist, but
 [multigrid](https://en.wikipedia.org/wiki/Multigrid_method)
-methods are often among the best choices for problems without 
-significant hyperbolic character.  
-The [HYPRE](application_development/hypre.md optional=true) package, 
-specifically the 
+methods are often among the best choices for problems without
+significant hyperbolic character.
+The [HYPRE](application_development/hypre.md optional=true) package,
+specifically the
 BoomerAMG preconditioner, is often a good choice for a preconditioner to
 condition the system of equations resulting from the MOOSE simulation.
 
@@ -401,11 +403,11 @@ Setting
 
 in the `[Executioner]` block will reuse the same preconditioner until
 the number of linear iterations required to solve the linearized system of
-equations exceeds 20.   If the number of linear iterations exceeds 
+equations exceeds 20.   If the number of linear iterations exceeds
 `reuse_preconditioner_max_linear_its`
 the system does not immediately stop iterating on the current linearized
 system.  Instead it will continue until it either successfully solves
-the current system or reaches `l_max_its`.  It will then form a new 
+the current system or reaches `l_max_its`.  It will then form a new
 preconditioner for the next nonlinear iteration.
 
 Using these parameters in combination with a direct factorization of the
@@ -429,13 +431,13 @@ when using an expensive preconditioner, like a direct solver, as shown
 in this example.
 
 There are two differences between
-`reuse_preconditioner` and 
-setting up preconditioner reuse directly in PETSc with the 
+`reuse_preconditioner` and
+setting up preconditioner reuse directly in PETSc with the
 `-snes_lag_preconditioner_persists` and `-snes_lag_preconditioner` options:
 1. `-snes_lag_preconditioner X` will recalculate a new preconditioner
    every X linear iterations, regardless of the progress of the linear solve.
    `reuse_preconditioner_max_linear_its = X` will continue to reuse
-   the same preconditioner until the number of linear iterations 
+   the same preconditioner until the number of linear iterations
    required to solve the linearized equations exceeds X.
 2. By default libmesh deletes the PETSc `SNES` instance after each time
    step.  This means that regardless of how the reuse options are set,
@@ -451,7 +453,7 @@ affects how PETSc solves the linearized system of equations formed
 at each nonlinear iteration.  Ideally, if the reused preconditioner
 achieves the requested `l_tol` precision before iterating more than
 `l_max_its` times, preconditioner reuse will not affect the
-convergence of the nonlinear iterations compared to a case with the 
+convergence of the nonlinear iterations compared to a case with the
 reuse option off.  As described above,
 preconditioner reuse aims to decrease the time required to solve
 the linearized equations at each nonlinear iteration by reducing the
@@ -460,10 +462,10 @@ linear preconditioner.
 
 By contrast, modified Newton methods will affect the nonlinear
 convergence of the system without affecting how PETSc solves the
-linearized system of equations.  The goal of 
+linearized system of equations.  The goal of
 modified Newton methods is to reduce the time required to solve
 the nonlinear equations by forming a new Jacobian matrix less often.
 
 Put another way, preconditioner reuse aims to speed up solving the
-linear system of equations while modified Newton methods aim to 
+linear system of equations while modified Newton methods aim to
 accelerate solving the nonlinear equations.

framework/doc/content/source/variables/MooseVariable.md

@@ -4,6 +4,8 @@
 
 A detailed description of the MOOSE variable system is given in the [base class documentation](MooseVariableBase.md).
 
+Mention that typical Residual and Jacobian are from Kernels, Constraints, etc.
+
 !syntax parameters /Variables/MooseVariable
 
 !syntax inputs /Variables/MooseVariable

framework/doc/content/source/variables/MooseVariableBase.md

@@ -1,5 +1,7 @@
 # MooseVariableBase
 
+Make first words below link to the variable type
+
 !syntax description /Variables/MooseVariableBase
 
 The current class hierarchy for Moose variables is shown below:

framework/doc/content/syntax/Constraints/index.md

@@ -1,5 +1,17 @@
 # Constraints System
 
+The `Constraints` system provides functionality for describing interaction and coupling
+between various nodes, elements or surfaces in a model for which the topology may evolve
+during the course of the solution. Generically, within an interaction pair, the two sides
+are referred to as +Element+ and +Neighbor+ or +Secondary+ and +Primary+. A few examples
+of constraints include contact, mesh tying, and periodic boundary conditions.
+
+Since the topology of the interacting nodes and elements may evolve, the direct contributions
+to the residual and the Jacobian need to be provided by the developer by overriding the
+`computeResidual()` and `computeJacobian()` functions directly. Certain examples for node
+and element constraints are listed in the syntax list at the bottom of the page. The remainder
+of the description is focused on the application of mortar constraints for surface interaction.
+
 ## MortarConstraints
 
 The mortar system in MOOSE uses a segment-based approach for evaluation of mortar integrals; for information on the automatic generation of mortar segment meshes see [AutomaticMortarGeneration.md].
@@ -107,6 +119,21 @@ There are also some optional parameters that can be supplied to
 
 At present, either the `secondary_variable` or `primary_variable` parameter must be supplied.
 
+## Coupling with Scalar Variables
+
+If the weak form has contributions from scalar variables, then this contribution can be
+treated similarly as coupling from other spatial variables. See the
+[`Coupleable`](/source/interfaces/Coupleable.md) interface for how to obtain the variable
+values. Residual contributions are simply added to the `computeQpResidual()` function.
+
+Because mortar-versions of `UserObjects` are not yet implemented, the only way to add
+contributions to the Jacobian, as well as the contribution of the mortar spatial variables
+to the scalar variable, is through deriving from the intermediate scalar base class
+[`MortarScalarBase`](source/constraints/MortarScalarBase.md). This class provides
+standard interfaces for quadrature point contributions to primary, secondary, lower, and
+scalar variables in the residual and Jacobian. Additional discussion can be found at
+[`ScalarKernels`](syntax/ScalarKernels/index.md).
+
 !syntax list /Constraints objects=True actions=False subsystems=False
 
 !syntax list /Constraints objects=False actions=False subsystems=True

framework/doc/content/syntax/Kernels/index.md

@@ -175,6 +175,19 @@ And the corresponding `computeQpJacobian()` is:
 return _test[_i][_qp] * _phi[_j][_qp] * _du_dot_du[_qp];
 ```
 
+## Coupling with Scalar Variables
+
+If the weak form has contributions from scalar variables, then this contribution can be
+treated similarly as coupling from other spatial variables. See the
+[`Coupleable`](/source/interfaces/Coupleable.md) interface for how to obtain the variable
+values. Residual contributions are simply added to the `computeQpResidual()` function.
+Jacobian terms from the test spatial variable and incremental scalar variable are added by
+overriding the function `computeQpOffDiagJacobianScalar()`.
+
+Contributions to the scalar variable weak equation (test scalar variable terms) are not
+natively treated by the `Kernel` class. Inclusion of these residual and Jacobian contributions
+are discussed within [`ScalarKernels`](syntax/ScalarKernels/index.md) and specifically
+[`KernelScalarBase`](source/kernels/KernelScalarBase.md).
 
 ## Further Kernel Documentation
 

framework/doc/content/syntax/ScalarKernels/index.md

@@ -12,6 +12,49 @@ time as the independent variable:
 where $u(t)$ is the dependent variable, $f(u, t)$ is the steady-state residual
 function, and $u_0$ is the initial value.
 
+Similar to the [Kernel](syntax/Kernels/index.md) class, in a `ScalarKernel` subclass the
+`computeResidual()` function +must+ be overridden.  This is where you implement
+your ODE weak form terms.  For non-AD objects the following member function can
+optionally be overridden:
+
+- `computeJacobian()`
+- `computeOffDiagJacobianScalar()`
+
+## Coupling with Spatial Variables
+
+For systems of coupled partial differential equations (PDEs) and ODEs, typically
+integration over domains and manifolds are needed within the coupling terms of the
+weak form. Since the `ScalarKernel` class does not provide for integration over
+elements or faces, there are two options for performing needed integration using
+other object classes:
+
+1. Compute integrals for residual and diagonal Jacobian entries of the scalar
+   variable within a `UserObject` and connect that value into the `ScalarKernel` object.
+   Cross Jacobian terms that couple the scalar and spatial variables need to be handled
+   by overridden assembly routines that access upper and lower triangular blocks of the
+   Jacobian concurrently. An example of this approach is provided in the
+   [AverageValueConstraint.md] and the [ScalarLagrangeMultiplier.md] objects, respectively.
+
+2. Compute all integrals for the residual and Jacobian entries for the spatial and
+   scalar variables using intermediate scalar base classes that derive from the
+   respective spatial variable residual object class. This approach is described below.
+
++REVISE+:
+
+The idea of each of these intermediate scalar base classes is that they add standard
+quadrature loops and assembly routines to handle the contributions from a single added
+scalar variable to that object, the entire row of the Jacobian. Lists of interfaces for
+the quadrature point routines are given in the links below. This system is currently being
+developed and will extend to the other residual objects.
+
+| Object | Intermediate Scalar Base Class | Example Derived Class |
+| :- | :- | :- |
+| Kernel\\ +ADKernel+ | [`KernelScalarBase`](source/kernels/KernelScalarBase.md) | [`ScalarLMKernel`](source/kernels/ScalarLMKernel.md) |
+| IntegratedBC | Under Development |  |
+| InterfaceKernel | Under Development |  |
+| DGKernel | Under Development |  |
+| MortarConstraint\\ +ADMortarConstraint+ | [`MortarScalarBase`](source/constraints/MortarScalarBase.md) | [`PeriodicSegmentalConstraint`](source/constraints/PeriodicSegmentalConstraint.md) |
+
 ## Automatic Differentiation
 
 Scalar kernels have the ability to be implemented with

framework/doc/content/syntax/Variables/index.md

@@ -1,5 +1,7 @@
 # Variables System
 
+Add link to variable base
+
 ## Description
 
 The `Variables` block within an input file is utilized to define the unknowns within a system

framework/include/constraints/ADMortarScalarBase.h

@@ -62,9 +62,12 @@ class ADMortarScalarBase : public ADMortarConstraint
    */
   virtual void initScalarQpResidual() {}
 
-  /// Whether to compute scalar contributions
+  /// Whether a scalar variable is declared for this constraint
   const bool _use_scalar;
 
+  /// Whether to compute scalar contributions for this instance
+  const bool _compute_scalar_residuals;
+
   /// A dummy object useful for constructing _kappa when not using scalars
   const ADVariableValue _kappa_dummy;
 

framework/include/constraints/MortarScalarBase.h

@@ -130,9 +130,12 @@ class MortarScalarBase : public MortarConstraint
   {
   }
 
-  /// Whether to compute scalar contributions
+  /// Whether a scalar variable is declared for this constraint
   const bool _use_scalar;
 
+  /// Whether to compute scalar contributions for this instance
+  const bool _compute_scalar_residuals;
+
   /// A dummy object useful for constructing _kappa when not using scalars
   const VariableValue _kappa_dummy;
 

framework/include/kernels/ADKernelScalarBase.h

@@ -72,9 +72,15 @@ class ADKernelScalarBase : public ADKernel
    */
   virtual void initScalarQpResidual() {}
 
-  /// Whether to compute scalar contributions
+  /// Whether a scalar variable is declared for this kernel
   const bool _use_scalar;
 
+  /// Whether to compute scalar contributions for this instance
+  const bool _compute_scalar_residuals;
+
+  /// Whether to compute field contributions for this instance
+  const bool _compute_field_residuals;
+
   /// A dummy object useful for constructing _kappa when not using scalars
   const ADVariableValue _kappa_dummy;