Modularize the entropy viscosity regularization

[shiyu-du-dsy]

This PR separate entropy viscosity from the Euler solver by doing the following steps:

1. Add a new simcomp call avm_simcomp_t for the model for the artificial viscosity method (AVM), which handle the operation of the new type avm_t . Now entropy_viscosity_t is the only one derived type of avm_t. This object is responsible for compute the entropy viscosity to be used at each time step.
2. Add a new class viscous_regularization_t to apply the artificial viscosity to the equation. So far there is only one derived type artificial_viscosity_t, but lately I will add the spectral vanishing viscosity (SVV) as another child.
3. To apply the viscous regularization, one needs to have both AVM simcomp and viscous regularization as the json entries. Just see the updated cases.

To do list:

• Documentation
• Updated examples
• Changelog

And regarding other regularization method such as GJP and HPF, since they do not act through the viscous term, we could keep them in the source term. (in the pnpn solver, viscous term is treated implicitly, therefore needs extra treatment)

[Copilot]

Pull request overview

This PR modularises entropy-viscosity-based artificial viscosity by splitting (1) the AVM model that computes a viscosity field from (2) the viscous regularisation that applies it in the solver, and wiring this through a new simulation component.

Changes:

• Introduces avm_model_t + avm_simcomp_t to compute and output an AVM viscosity field (currently entropy_viscosity).
• Adds viscous_regularization_t + artificial_viscosity_t and refactors the compressible Euler scheme to update effective_visc via the new interface.
• Moves/extends CPU + device backends for entropy viscosity and updates docs/examples accordingly.

Reviewed changes

Copilot reviewed 22 out of 30 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
src/viscous_regularization/viscous_regularization.f90	Renames/specialises the base regularisation abstraction to viscous regularisation.
src/viscous_regularization/viscous_regularization_fctry.f90	Factory for viscous regularisation implementations.
src/viscous_regularization/artificial_viscosity.f90	New viscous-regularisation implementation that applies AVM viscosity to effective_visc.
src/viscous_regularization/avm_model/avm_model.f90	New AVM model base type and registry field setup.
src/viscous_regularization/avm_model/avm_model_fctry.f90	Factory/registration mechanism for AVM models.
src/viscous_regularization/avm_model/entropy_viscosity.f90	Refactors entropy viscosity to be an AVM model (preprocess/compute split).
src/viscous_regularization/avm_model/bcknd/cpu/entropy_viscosity_cpu.f90	New CPU backend module for entropy viscosity kernels.
src/viscous_regularization/avm_model/bcknd/device/entropy_viscosity_device.F90	New device-dispatch backend for entropy viscosity kernels.
src/viscous_regularization/avm_model/bcknd/device/cuda/entropy_viscosity.cu	New CUDA kernel launcher implementations.
src/viscous_regularization/avm_model/bcknd/device/cuda/entropy_viscosity_kernel.h	New CUDA kernels (entropy residual/viscosity/max/clamp/smooth).
src/viscous_regularization/avm_model/bcknd/device/hip/entropy_viscosity.hip	New HIP kernel launcher implementations.
src/viscous_regularization/avm_model/bcknd/device/hip/entropy_viscosity_kernel.h	New HIP kernels (entropy residual/viscosity/max/clamp/smooth).
src/viscous_regularization/avm_model/bcknd/device/opencl/entropy_viscosity.c	New OpenCL kernel launcher implementations.
src/viscous_regularization/avm_model/bcknd/device/opencl/entropy_viscosity_kernel.cl	New OpenCL kernels (entropy residual/viscosity/max/clamp/smooth).
src/simulation_components/avm_simcomp.f90	New simcomp to drive AVM model preprocess/compute and output.
src/simulation_components/simulation_component_fctry.f90	Registers the new avm_model simcomp type.
src/fluid/fluid_scheme_compressible_euler.f90	Switches Euler scheme from embedded regularisation to viscous_regularization update.
src/fluid/euler_res.f90	Updates RHS interface to remove h argument.
src/fluid/bcknd/cpu/euler_res_cpu.f90	Updates CPU RHS implementation signatures to match new interface.
src/fluid/bcknd/device/euler_res_device.F90	Updates device RHS implementation signatures to match new interface.
src/Makefile.am	Updates build lists to add new AVM/regularisation sources and remove old ones.
src/.depends	Regenerated dependency file reflecting new modules/paths.
src/.depends_device	Regenerated device dependency file reflecting new module paths.
examples/euler_tgv/euler_tgv.case	Updates example to use avm_model simcomp + viscous_regularization config.
examples/euler_2d_smooth/euler_2d_smooth.case	Updates example to use avm_model simcomp + viscous_regularization config.
examples/euler_2d_forward_facing_step/step.case	Updates example to use avm_model simcomp + viscous_regularization config.
examples/euler_2d_cylinder/euler_2d_cylinder.case	Updates example to use avm_model simcomp + viscous_regularization config.
examples/euler_1d_sod/sod.case	Updates example to use avm_model simcomp + viscous_regularization config.
doc/pages/user-guide/simcomps.md	Documents the new avm_model simcomp and its configuration.
doc/pages/user-guide/case-file.md	Documents viscous regularisation configuration and updates compressible example.

Comments suppressed due to low confidence (4)

src/viscous_regularization/avm_model/entropy_viscosity.f90:127

• The select type (fluid => case%fluid) block has no class default/error path. If case%fluid is not fluid_scheme_compressible_t, the field pointers (S/u/v/w/max_wave_speed/msh/Xh/gs) remain null and later calls will dereference them. Add an explicit default case that errors out (or handle additional fluid types) to avoid null pointer crashes.
  src/viscous_regularization/avm_model/entropy_viscosity.f90:119
• c_avisc_low defaults to 1.0 here, but the user-guide documentation (and prior compressible numerics defaults) state 0.5. Either update the code default back to 0.5 or update the documentation consistently; otherwise users will see unexpected behaviour changes when omitting the parameter.
  src/viscous_regularization/viscous_regularization.f90:112
• viscous_regularization_t has an allocatable component reg_coeff_name, but free_base does not deallocate it. Base destructors should deallocate allocatable components (and nullify pointer components) to avoid leaks/stale state on reinitialisation.
  src/viscous_regularization/avm_model/entropy_viscosity.f90:114
• reg_coeff_name is a local allocatable that becomes allocated via json_get_or_default, but it is not deallocated before returning. Project guidelines require explicit deallocation of local allocatables allocated within a subroutine.

[timofeymukha]

Avm_model become artificial viscosity method model. I kinda feel like u should choose either model or method and just write ot out, for example, artificial_viscosity_method

[shiyu-du-dsy]

I will rebase it after the compressible Navier-Stokes PR is merged :)

[tuananhdao]

I will rebase it after the compressible Navier-Stokes PR is merged :)

Thank you for that :) I hope it will not be a hassle.

[shiyu-du-dsy]

Now it's fixed with the latest compressible ns push

[timofeymukha]

I think is all fine basically, just some comments.

The axhelm edit makes me scared...

[njansson]

I think is all fine basically, just some comments.

The axhelm edit makes me scared...

It was me who forced pushed the buggy vector version a week or so ago

[timofeymukha]

@shiyu-du-dsy It seems Codex found some important stuff!

1. [P1] Entropy history is updated in the wrong order.
   entropy_viscosity_update_lag computes the new entropy before shifting the lag series. Consequently, at step 4 both S and S_lag(1) contain step 3, while step 0 is missing. The
   BDF3 residual is therefore incorrect. Shift the lag series first, then recompute S.

2. [P1] Existing case files are silently accepted but lose stabilization.
   The solver no longer reads case.numerics.c_avisc_low or c_avisc_entropy, and it disables regularization when the new fluid object is absent (setup logic). However, the numerics
   schema still accepts both obsolete parameters. Existing validated cases will therefore run without artificial viscosity instead of failing or preserving old behavior. Either
   provide backward compatibility or reject the old configuration and mark the change as breaking. Tim: let's reject

3. [P1] Restart does not reconstruct the three entropy history levels.
   avm_simcomp_restart calls compute once. At a restarted tstep > 3, only one lag entry is populated; the next preprocessing pass evaluates BDF3 using zero/uninitialised older
   entries. The lag fields need checkpoint support or a safe restart initialization such as filling all levels with the restarted entropy.

4. [P2] Updated examples output an unrelated, empty S field.
   The model initializes its private entropy as entropy_viscosity_S without registering it (lines 138–140), while all five examples still request "S" (Sod example). field_writer
   silently registers a new zero-valued S, so the output looks valid but is wrong. Register the model entropy under the documented name or remove/update these output entries.

5. [P2] The base destructor does not release all owned state.
   viscous_regularization_t owns reg_coeff, reg_coeff_name, coef, and dof, but free_base only nullifies the last two. It should also nullify reg_coeff and explicitly deallocate
   reg_coeff_name. Additionally, the local allocatable reg_coeff_name in entropy_viscosity_init is not manually deallocated as required by the repository guidelines.

6. [P2] A non-compressible case leaves the model partially initialized and then dereferences null pointers.
   The select type has no default/error branch, yet compute_entropy is called immediately afterward. If this globally available simcomp is added to a PnPn case, p and rho remain
   null. Initialization should reject unsupported fluid schemes explicitly.

7. [P2] Documentation does not describe a working configuration.
   The compressible-flow example includes only viscous_regularization, omitting the AVM simcomp that computes its coefficient, so copied configurations get zero viscosity. The
   later statement that this works for scalar equations is also unsupported by this PR. The new section additionally lacks the mandatory header tag, and several new modules/types/
   procedures lack required Doxygen documentation. Modified 2025-licensed source files should include 2026 in their copyright range.

[shiyu-du-dsy]

Note that in the current version, the restart will re-compute the entropy viscosity based on the latest state in 1st order. For a real clean restart, the p_lag and rho_lag should be included in the check point file as well. However noting that restart is not in effect in the compressible solver, I would like to keep the issue to a fixing PR for the restart of the compressible solver.