SQA and docs (idaholab#22563)

framework/doc/content/source/interfaces/Coupleable.md

@@ -142,3 +142,22 @@ DOFs all the user to perform their own integration or other evaluation without g
 process. These functions can be found here:
 
 !listing framework/include/interfaces/Coupleable.h start=coupled-dof-values-begin end=coupled-dof-values-end include-start=false
+
+## Writing directly to coupled variables
+
+Element- and nodal user objects as well AuxKernels may obtain a writable reference to a MOOSE field variable
+through the `Coupleable::writableVariable` function. The returned variable reference provides a `setNodalValue`
+method that can be used to set the nodal or elemental DOF value(s) of the variable.
+
+`Coupleable::writableVariable` enforces compatibility between the calling object type and the family of the
+requested variable. I.e. nodal user objects and AuxKernels may only obtain references to nodal variables, and
+element user objects and elemental AuxKernels may only obtain references to elemental variables.
+
+The block restrictins of the variables are also checked not to exceed the block restrictions of the calling object.
+MOOSE keeps track of all variables to which a reference was obtained through `Coupleable::writableVariable`. Each
+variable in the system may at most be written to by a single object (this might be relaxed in the future to permit
+multiple object with non overlapping block restrictions to obtain a writable reference).
+
+The user object and aux kernel thread loops check if an executed object has any writable variable references, and
+if so, will insert those variables into the aux solution vector. This obviates the need for using the
+[`SelfAux`](SelfAux.md) kernel.

framework/src/interfaces/Coupleable.C

@@ -854,6 +854,15 @@ Coupleable::writableVariable(const std::string & var_name, unsigned int comp)
                "'.");
   // if (nuo && !var->isNodal()) is handled by checkVar already
 
+  // check block restrictions for compatibility
+  const auto * br = dynamic_cast<const BlockRestrictable *>(this);
+  if (!var->hasBlocks(br->blocks()))
+    mooseError("The variable '",
+               var->name(),
+               "' must be defined on all blocks '",
+               _obj->name(),
+               "' is defined on");
+
   // make sure only one object can access a variable
   for (const auto & ci : _obj->getMooseApp().getInterfaceObjects<Coupleable>())
     if (ci != this && ci->_writable_coupled_variables[_c_tid].count(var))

test/tests/auxkernels/nodal_aux_var/tests

@@ -1,6 +1,6 @@
 [Tests]
-  issues = '16769b212846275cd8b12e5a89b9e98f3ab7ca83'
-  design = 'syntax/AuxKernels/index.md'
+  issues = '16769b212846275cd8b12e5a89b9e98f3ab7ca83 #22563'
+  design = 'syntax/AuxKernels/index.md Coupleable.md'
   [init_test]
     type = 'Exodiff'
     input = 'nodal_aux_init_test.i'
@@ -46,7 +46,8 @@
     input = 'multi_update_elem_var_test.i'
     exodiff = 'out_multi_elem_var.e'
     requirement = "The MOOSE auxiliary system shall be capable of updating multiple elemental "
-                  "auxiliary variables within a single AuxKernel object."
+                  "auxiliary variables within a single AuxKernel object, including the kernel "
+                  "variable itsef using the setNodalValue method."
   []
   [multi_update_elem_test_coupled_value]
     type = 'Exodiff'
@@ -62,7 +63,8 @@
     input = 'multi_update_elem_var_test.i'
     cli_args = 'AuxVariables/ten/order=FIRST AuxVariables/ten/family=LAGRANGE'
     expect_err = "The AuxKernel 'all' and the variable 'ten' must both either be nodal or elemental."
-    requirement = "The MOOSE auxiliary system shall check compatibility between primary and writable coupled variables."
+    requirement = "The MOOSE auxiliary system shall check compatibility between primary and writable "
+                  "coupled variables."
   []
 
   [ts_test]

test/tests/userobjects/writable_variable/tests

@@ -1,25 +1,47 @@
 [Tests]
+  issues = '#22563'
+  design = 'Coupleable.md
+
   [nodal]
     type = Exodiff
     input = nodal.i
     exodiff = nodal_out.e
+    requirement = "The system shall allow nodal user objects to obtain writable references to nodal variables."
   []
   [elemental]
     type = Exodiff
     input = elemental.i
     exodiff = elemental_out.e
+    requirement = "The system shall allow elemental user objects to obtain writable references to elemental variables."
   []
 
   [nodal_error]
     type = RunException
     input = nodal.i
     cli_args = 'AuxVariables/v/family=MONOMIAL AuxVariables/v/order=CONSTANT'
     expect_err = 'nodal: cannot couple elemental variables into nodal objects'
+    requirement = "The system shall prevent nodal user objects from obtaining writable references to elemental variables."
   []
   [elemental_error]
     type = RunException
     input = elemental.i
     cli_args = 'AuxVariables/v/family=LAGRANGE AuxVariables/v/order=FIRST'
     expect_err = "The ElementUserObject 'elemental' cannot obtain a writable reference to the nodal variable 'v'."
+    requirement = "The system shall prevent elemental user objects from obtaining writable references to nodal variables."
+  []
+
+  [block]
+    type = Exodiff
+    input = block.i
+    exodiff = block_out.e
+    cli_args = 'UserObjects/elemental/block=1'
+    requirement = "The system shall allow block restricted user objects to obtain a writable reference to a variable with a block restriction that includes the user object's blocks"
+  []
+  [block_error]
+    type = RunException
+    input = block.i
+    cli_args = 'AuxVariables/v/block=1'
+    expect_err = "The variable 'v' must be defined on all blocks 'elemental' is defined on"
+    requirement = "The system shall enforce that all variables an object obtains a writable reference to are defined on all of the object's blocks"
   []
 []