Support full initialization of volumetric maps within Colvars

[giacomofiorin]

Currently, volumetric map and Multi-Map variables (link) are implemented in NAMD in two ways:

1. using MGridForce keywords, with atoms selected by MGridForceFile and scalable computation over multiple processors/nodes done by NAMD as implemented here (more efficient)
2. using MGridForce keywords, but with atoms selected and processed internally by Colvars (more flexible)

In VMD the situation is similar, with MGridForce replaced by VMD commands and with the distinction that

This PR improves the use-case no. 2, i.e. when atoms are selected and processed directly by Colvars. It allows to specify the volumetric map's file name directly in the Colvars configuration, with the following advantages:

• there is no need for an additional Tcl script to load the maps
• the syntax is now identical to NAMD and VMD

One disadvantage of processing the atoms and the maps internally to Colvars is that NAMD's parallel communication cannot be used any more (use-case no. 1). However, in today's most GPU-based computations there are not many CPU tasks.

The documentation and the Colvars Dashboard template for mapTotal are updated accordingly. Additionally, there is now a template configuration for a Multi-Map variable as well (although using the generator script is still preferred)

[HanatoK]

It seems with this PR and NAMD's main branch, the interface volmap tests are still failed either in the CPU build or in the GPU build. Do I miss something?

[giacomofiorin]

It seems with this PR and NAMD's main branch, the interface volmap tests are still failed either in the CPU build or in the GPU build.

Correct, this PR tries to fix the issue of NAMD raising an error when gridForces are defined with GPU-resident, even if they are never meant to be used on the GPU. By making Colvars load them instead, the user's intent is much clearer.

The issue of NAMD main no longer supporting reduction via ComputeGlobal (on any hardware configuration) still remains unaddressed. (EDIT: Should be fixed soon as of April 2026, but performance with GPU-resident is not great)

[jhenin]

Is this ready for review?

[giacomofiorin]

@jhenin I have a few jobs that showed discontinuities upon restarting: likely a PBC issue. I converted it back to draft accordingly.

[giacomofiorin]

After rebasing onto master:

• NAMD ARM volmap regtests fail, but this looks like another instance of single-precision math
• VMD volmap tests segfault

[giacomofiorin]

All tests pass now, minus the small numerical deviations in AMD64 due to the use of the NAMD GridForces code, which uses single-precision math. I disabled those.