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.

[HanatoK]

Looks good to me overall.

[Copilot]

Pull request overview

Adds Colvars-managed volumetric-map loading through mapFile for NAMD and VMD, with supporting Multi-Map generation, documentation, templates, and tests.

Changes:

• Separates engine-managed and internally computed map APIs.
• Adds internal DX loading and Multi-Map generator support.
• Updates documentation, templates, fixtures, and golden outputs.

Reviewed changes

Copilot reviewed 42 out of 44 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
vmd/tests/interface/005_multiple_maps/AutoDiff/test.colvars.traj	Updates VMD trajectory baseline.
vmd/tests/interface/005_multiple_maps/AutoDiff/test.colvars.out	Updates VMD log baseline.
vmd/tests/interface/004_map_total_internal/AutoDiff/test.colvars.traj	Updates internal-map trajectory baseline.
vmd/tests/interface/004_map_total_internal/AutoDiff/test.colvars.out	Updates internal-map log baseline.
vmd/src/colvarproxy_vmd.h	Declares internal-map APIs.
vmd/src/colvarproxy_vmd.C	Implements VMD DX loading and indexed computation.
vmd/cv_dashboard/templates/component.colvars	Adds mapFile and Multi-Map templates.
src/colvarproxy_volmaps.h	Separates engine and internal map interfaces.
src/colvarproxy_volmaps.cpp	Implements shared map bookkeeping.
src/colvarcomp_volmaps.cpp	Adds mapFile parsing and execution paths.
namd/tests/library/Common/origin.pdb	Adds density-generation origin fixture.
namd/tests/library/Common/make_densities.tcl	Expands and recenters generated maps.
namd/tests/interface/007_map_total_internal/test.in	Exercises NAMD mapFile loading.
namd/tests/interface/007_map_total_internal/skip_test.sh	Skips the test on AArch64.
namd/tests/interface/007_map_total_internal/namd-version.txt	Updates recorded runtime version.
namd/tests/interface/007_map_total_internal/AutoDiff/test.restart.colvars.traj	Updates restart trajectory baseline.
namd/tests/interface/007_map_total_internal/AutoDiff/test.restart.colvars.state.stripped	Updates restart-state baseline.
namd/tests/interface/007_map_total_internal/AutoDiff/test.restart.colvars.out	Updates restart log baseline.
namd/tests/interface/007_map_total_internal/AutoDiff/test.colvars.traj	Updates trajectory baseline.
namd/tests/interface/007_map_total_internal/AutoDiff/test.colvars.state.stripped	Updates state baseline.
namd/tests/interface/007_map_total_internal/AutoDiff/test.colvars.out	Updates log baseline.
namd/tests/interface/006_multiple_maps/namd-version.txt	Updates recorded runtime version.
namd/tests/interface/006_multiple_maps/AutoDiff/test.restart.colvars.traj	Updates restart trajectory baseline.
namd/tests/interface/006_multiple_maps/AutoDiff/test.restart.colvars.state.stripped	Updates restart-state baseline.
namd/tests/interface/006_multiple_maps/AutoDiff/test.restart.colvars.out	Updates restart log baseline.
namd/tests/interface/006_multiple_maps/AutoDiff/test.colvars.traj	Updates Multi-Map trajectory baseline.
namd/tests/interface/006_multiple_maps/AutoDiff/test.colvars.state.stripped	Updates Multi-Map state baseline.
namd/tests/interface/006_multiple_maps/AutoDiff/test.colvars.out	Updates Multi-Map log baseline.
namd/tests/interface/005_map_total_cvc/skip_test.sh	Skips the test on AArch64.
namd/tests/interface/005_map_total_cvc/namd-version.txt	Updates recorded runtime version.
namd/tests/interface/005_map_total_cvc/AutoDiff/test.restart.colvars.traj	Updates restart trajectory baseline.
namd/tests/interface/005_map_total_cvc/AutoDiff/test.restart.colvars.state.stripped	Updates restart-state baseline.
namd/tests/interface/005_map_total_cvc/AutoDiff/test.restart.colvars.out	Updates restart log baseline.
namd/tests/interface/005_map_total_cvc/AutoDiff/test.colvars.traj	Updates trajectory baseline.
namd/tests/interface/005_map_total_cvc/AutoDiff/test.colvars.state.stripped	Updates state baseline.
namd/tests/interface/005_map_total_cvc/AutoDiff/test.colvars.out	Updates log baseline.
namd/src/GlobalMaster.C.patch	Initializes grid-object iterator state.
namd/src/colvarproxy_namd.h	Declares NAMD internal-map storage and APIs.
namd/src/colvarproxy_namd.C	Implements NAMD map loading and engine integration.
doc/colvars-refman-main.tex	Documents mapFile and Multi-Map usage.
devel-tools/compile-vmd.sh	Enables VMD debug symbols.
colvartools/gen_multimap.py	Adds internal loading and generator options.

Suppressed comments (5)

colvartools/gen_multimap.py:1030

• Changing this default to False makes the if args.use_pdb_weights is None auto-enable branch in check_prep_args() unreachable. Consequently, supplying --input-pdb-files no longer enables PDB weights by default, contrary to the option's help and prior behavior.

    group.add_argument('--use-pdb-weights',
                       action='store_true',
                       help='When true, multiply the occupancy and temperature '
                       'PDB columns to define the weights of each atom within '
                       'each map; when false, all weights are equal to 1. '
                       'Defaults to True if --input-pdb-files is used.',
                       default=False)

colvartools/gen_multimap.py:1190

• This assignment discards a mask loaded through --deformation-map-mask whenever --mask-by-amplitude is also set. Both option descriptions explicitly allow combining masking functions, so the amplitude mask must be multiplied into the existing mask as before.

        args.deformation_map_mask = \
            get_mask_from_deformation(deformation_map=args.deformation_map,
                                      threshold=mask_threshold,
                                      tolerance=0.2*mask_threshold)

colvartools/gen_multimap.py:1384

• For a 2D workflow with multiple input selections (for example upper and lower leaflets), this fallback chooses only the first PDB file. The previous implementation built averaged distanceZ components for every unique selection, so generated scripts now restrain one leaflet instead of the system COM. Preserve all input selections when no explicit --com-restraint-pdb-file is supplied.

        com_pdb_file = ori_pdb_file = args.com_restraint_pdb_file
        if com_pdb_file is None:
            com_pdb_file = ori_pdb_file = pdb_files[0]

colvartools/gen_multimap.py:1036

• The help says this option has no effect in VMD, but write_vmd_script() uses it to suppress mol addfile and generate mapFile components. Users therefore cannot rely on the documented behavior; describe that internal loading applies to both NAMD and VMD.

                       help="When true, Colvars will load the maps internally using "
                       "\"mapFile\" and the atoms are processed diretly by Colvars "
                       "instead of NAMD; "
                       "this option has no effect in VMD",

doc/colvars-refman-main.tex:4090

• This second link has the same visible-keyword error: weights require an atoms group, not mapName. As written, the public reference directs users to configure an incompatible map identifier.

    This option requires defining using the \refkey{mapName}{colvar|mapTotal|atoms} keyword to select atoms, and the number of weights must match the number of atoms.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.