Improve the AD docs

[nmnobre]

Hi Alex (@lindsayad),

I thought it'd be a good idea to read a bit on AD, since it's been such a stone in my shoe recently. 😅

So, why do we skip the local assembly to _local_re and _local_ke? Is it just older code or is it a conscious design decision for a particular reason? It sounded like the latter.

EDIT: It seems like you removed the option to switch between NumberArray and SemiDynamicSparseNumberArray almost a year ago now, ~so maybe the docs require bigger changes~ so I tried to reword the docs to accommodate for that.

Cheers, -N

[moosebuild]

Job Documentation on 9f0fa85 wanted to post the following:

View the site here

This comment will be updated on new commits.

[moosebuild]

Job Coverage on 9f0fa85 wanted to post the following:

Framework coverage

	cee3f6	#26630 9f0fa8
	Total	Total	+/-	New
Rate	85.24%	85.24%	+0.00%	-
Hits	99136	99137	+1	0
Misses	17167	17166	-1	0

Diff coverage report

Full coverage report

Modules coverage

Coverage did not change

Full coverage reports

Reports

• framework
• chemical_reactions
• combined
• contact
• electromagnetics
• external_petsc_solver
• fluid_properties
• fsi
• functional_expansion_tools
• geochemistry
• heat_transfer
• level_set
• misc
• navier_stokes
• optimization
• peridynamics
• phase_field
• porous_flow
• ray_tracing
• rdg
• reactor
• richards
• scalar_transport
• solid_properties
• stochastic_tools
• tensor_mechanics
• thermal_hydraulics
• xfem

This comment will be updated on new commits.

[lindsayad]

So, why do we skip the local assembly to _local_re and _local_ke?

As mentioned in https://github.com/idaholab/moose/pull/26595#pullrequestreview-1837230322 we could use _local_re, but for the Jacobian we would have to map from global indices to local indices (do a std::find in _var.dofIndices()) which would likely be too expensive for what we would gain (which was nothing really until you put up https://github.com/idaholab/moose/pull/26595 :smile:).

[lindsayad]

do a std::find in _var.dofIndices()

Of course after having written this I realized that this is a dramatic simplification. This ignored arbitrary coupling of variables and for FV in particular up to a 3 layer coupled element stencil (dofIndices() only gets you the dof indices of a single element)

[nmnobre]

So, why do we skip the local assembly to _local_re and _local_ke?

As mentioned in #26595 (review) we could use _local_re, but for the Jacobian we would have to map from global indices to local indices (do a std::find in _var.dofIndices()) which would likely be too expensive for what we would gain (which was nothing really until you put up #26595 😄).

I suppose I don't yet quite understand why we're using global dofs in the first place. All the magic to extract the Jacobian from the residual seems to be happening in Assembly::cacheJacobian() in Assembly.h, is that right?

[lindsayad]

I suppose I don't yet quite understand why we're using global dofs in the first place

because if you have a residual that depends on degrees of freedom for all the elements within a 3 neighbor layer, then it is pretty hard to come up with a local numbering scheme. It's super easy when forming an arbitrarily complex residual to do forward mode AD seeding the derivatives with the global dof index because you know it is unique