[giacomofiorin]

This PR contains an implementation of the code to reuse the output of certain computations between colvar component (CVC) objects. The scheme aims to provide support a broader set of use cases than the ones described in #232, i.e. it aims to share specific pieces of computation between CVCs of different types, as well as allowing concurrent application of forces.

The proposed scheme works as follows. In the configuration string of CVC_B, a reference is provided to CVC_A, which is an object been defined previously in the Colvars config. The type of CVC_A may be the same as CVC_B (in which case its value is simply copied), or it may be a base class of CVC_B, or the same as one of its members. In the latter two cases, It's assumed that the computation of CVC_B can be written as follows:

1. Read atomic coordinates
2. Compute a quantity using CVC_A's code
3. Store that quantity in a member or temporary variable
4. Compute another quantity using CVC_B's code, but using the previous quantity as input

When CVC_A is an object that was already computed, CVC_B can skip the first two steps altogether, and just replace the third step with an assignment.

This PR adds the ability to reuse an orientation component in a tilt, spinAngle, euler{Phi,Theta,Psi}, component. Other potential use cases, not covered in this PR, are:

• Reusing a distanceVec component as input to distance, distanceZ, distanceXY, etc.
• Reusing a generic "sum of squares" as input for gyration, inertia, inertiaZ, etc
• Reusing the computation of the individual "nodes" in a pair of path CVs ("s" and "z").
• Reusing the optimal rotation in a RMSD, and the latter in an eigenvector variable (Note: this would take some work, as those two classes have substantial feature creep).

In all of the above, the speedup would be either 2 or 3, assuming that the explicit loop over atoms is speed-limiting. (The inertia tensor has six independent components, but I assume that very few would be interested in biasing them all!)

Because the SMP loop over objects is currently unaware of the mutual dependencies, the reuseComponent keyword is not be allowed in the default case (smp on or smp cvcs). Using it would require that smp off, smp inner_loop or smp gpu are used instead. Future improvements may lift this constraint, e.g. by leveraging the fact that currently only one level of reusal is allowed.

Implements #232

[HanatoK]

Hi @giacomofiorin! It seems there is no change to the SMP related code, but maybe I miss somethign. If a cvc reuses other ones, how does the SMP work?

[giacomofiorin]

Hi @giacomofiorin! It seems there is no change to the SMP related code, but maybe I miss somethign. If a cvc reuses other ones, how does the SMP work?

See the last paragraph description. What I would like to do is keep a list of reusable CVCs, and run those first over SMP.

[HanatoK]

Hi @giacomofiorin! It seems there is no change to the SMP related code, but maybe I miss somethign. If a cvc reuses other ones, how does the SMP work?

See the last paragraph description. What I would like to do is keep a list of reusable CVCs, and run those first over SMP.

Thanks! I am working on linearCombination and customColvar at first, and they are supposed to reuse all other CVCs. In my opinion, all CVCs should be reusable. Maybe we can add a new user option like reuseThisCV for all CVCs to let the users control whether a CVC is reused.

[giacomofiorin]

Thanks! I am working on linearCombination and customColvar at first, and they are supposed to reuse all other CVCs. In my opinion, all CVCs should be reusable. Maybe we can add a new user option like reuseThisCV for all CVCs to let the users control whether a CVC is reused.

That's one option, but then all CVC classes would then need to have the necessary API changes. Okay with you if we discuss more next week?

[HanatoK]

Thanks! I am working on linearCombination and customColvar at first, and they are supposed to reuse all other CVCs. In my opinion, all CVCs should be reusable. Maybe we can add a new user option like reuseThisCV for all CVCs to let the users control whether a CVC is reused.

That's one option, but then all CVC classes would then need to have the necessary API changes. Okay with you if we discuss more next week?

OK.

[giacomofiorin]

Also, linearCombination and customColvar are cheap enough that we can always run them at the end, outside of SMP (the same as the polynomial superposition code in colvar::collect_cvc_values()).

So it would make sense to make them special cases.

[HanatoK]

I just doubt if it is really necessary to distribute the CVCs to different threads. On one hand, if the thread for CVC_A takes longer time to finish, then the thread for CVC_B has to wait. On the other hand, it makes the reusable CVCs complicated. I still think it would be better if Colvars can give up distributing CVCs among threads completely, and use the threads in fine-grained cases, such as calculating correlation and overlapping matrices in optimal rotation, rotating atoms, and projecting a hill in metadynamics...

[jhenin]

The main use case for distributing CVCs over threads is that of multiple, expensive CVCs of similar computational cost. It is hard to know how widespread it is, but in that case, the current implementation has the benefit of improving performance transparently without user intervention.

[HanatoK]

The main use case for distributing CVCs over threads is that of multiple, expensive CVCs of similar computational cost. It is hard to know how widespread it is, but in that case, the current implementation has the benefit of improving performance transparently without user intervention.

If the expensive CVCs refer to RMSD, anything related to optimal alignment and coordNum, then it is still better to distribute the expensive loops in a single CVC over threads instead of distribute CVCs themselves over threads. The former approach is more friendly to CPU caches, especially the shared L3 cache, because the CPU could fetch a large chunk of continuous data, instead of many small blocks, from the main memory to L3 directly for all threads. Moreover, distributing the inner loops in a CVC over threads can guarantee to accelerate the calculation of the most expensive CVC. Distributing CVCs over threads means that the slowest CVC uses always a single thread, and if there are other fast CVs (for example, using RMSD, gyration and a few distances), then the other threads have to wait for the slowest done.

[HanatoK]

I am looking into ways to parallelize the computation of CVCs even if there are interdependencies. With the dependencies the CVCs are in a compute graph. A way to parallelize the computation could be:

1. Considering A is the parent of B if A reuses B;
2. Finding the CVCs that have no parents as "starting points" (similar to the pilot action in PLUMED if you are familiar with its code);
3. Traversing the compute graph and finding the maximum depth of all CVCs from the starting points;
4. Now each CVC should has different depth, and then we can group CVCs according to their max depths into vectors.
5. Step 4 gives us a vector of vectors, and then we can compute all CVCs by reverisbly iterating the vector, and parallelizing the CVCs that have the same max depth.

For example, in the following compute graph,

we can compute all "depth=3" cvcs at first, and the all "depth=2". Each depth group could be parallelized. The code can be found in https://github.com/HanatoK/miscellaneous_scripts/blob/8ed465bbe5f7ccf0d950b7d10449be95443c386d/walk_graph/test.cpp#L112-L143

Now the major issue is that Colvars actually does not distribute CVCs over threads, and instead, the parallelization scheme is worse than I expect. It distributes the outermost colvar over threads!

[HanatoK]

There should be an additional reusability improvement about applying biasing force only to a single value of a vector CV, so that we can safely compute some CVs in a single CVC and output a vector, and then bias only a scalar part of the vector.

[giacomofiorin]

Now the major issue is that Colvars actually does not distribute CVCs over threads, and instead, the parallelization scheme is worse than I expect. It distributes the outermost colvar over threads!

Hi @HanatoK the loop is done over colvar objects to avoid having the top-level class reach too deep into the CVCs. However, in the case of a colvar with multiple CVCs, that colvar will appear in the loop multiple times to achieve parallelism over the entire collection of CVC objects.

colvars/src/colvarmodule.h

Lines 273 to 277 in 0f2d682

	/// Collective variables to be calculated on different threads;
	/// colvars with multple items (e.g. multiple active CVCs) are duplicated
	std::vector<colvar *> colvars_smp;
	/// Indexes of the items to calculate for each colvar
	std::vector<int> colvars_smp_items;

Your other comments all make sense, especially regarding building a dependency tree and do multiple parallel loops, one for each level. This PR is meant to introduce only one level to start with.

[Copilot]

🟡 Changes recommended

Reuse validation is bypassed, force signs can be incorrect, and SMP execution has an unresolved data race.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds reusable orientation computation across CVC objects, implementing the first phase of issue #232.

Changes:

• Adds named CVC registration and reuse dependencies.
• Refactors quaternion rotation calculations and force propagation.
• Adds spin-angle reuse regression fixtures.

File summaries

File	Description
tests/spinangle-reuse.in	Adds reuse configuration test.
tests/input_files/spinangle-reuse_harmonic-fixed/test.in	Adds harmonic reuse test.
tests/build_tests.sh	Registers the new test.
src/colvartypes.h	Moves rotation operations onto quaternions.
src/colvartypes.cpp	Implements quaternion rotation operations.
src/colvarmodule.h	Adds CVC registry and smart-pointer ownership.
src/colvarmodule.cpp	Implements registry, lifecycle, and output updates.
src/colvardeps.h	Defines CVC reuse features.
src/colvarcomp.h	Adds reusable-CVC state and orientation helpers.
src/colvarcomp.cpp	Implements registration and reuse validation.
src/colvarcomp_rotations.cpp	Reuses orientation values and forwards forces.
src/colvarbias.cpp	Adjusts trajectory spacing.
src/colvar.h	Exposes reference cleanup.
src/colvar.cpp	Registers and dereferences named components.
namd/tests/library/000_spinangle-reuse_harmonic-fixed/test.in	Adds NAMD reuse configuration.
namd/tests/library/000_spinangle-reuse_harmonic-fixed/notes.txt	Documents fixture provenance.
namd/tests/library/000_spinangle-reuse_harmonic-fixed/namd-version.txt	Records fixture environment.
namd/tests/library/000_spinangle-reuse_harmonic-fixed/AutoDiff/test.restart.colvars.traj	Adds restart trajectory reference.
namd/tests/library/000_spinangle-reuse_harmonic-fixed/AutoDiff/test.restart.colvars.state.stripped	Adds restart state reference.
namd/tests/library/000_spinangle-reuse_harmonic-fixed/AutoDiff/test.restart.colvars.out	Adds restart output reference.
namd/tests/library/000_spinangle-reuse_harmonic-fixed/AutoDiff/test.colvars.traj	Adds trajectory reference.
namd/tests/library/000_spinangle-reuse_harmonic-fixed/AutoDiff/test.colvars.state.stripped	Adds state reference.
namd/tests/library/000_spinangle-reuse_harmonic-fixed/AutoDiff/test.colvars.out	Adds output reference.

Review details

Suppressed comments (1)

src/colvarcomp_rotations.cpp:285

• dx_dq is the derivative with respect to the raw rotation q, but the source orientation's apply_force() interprets its argument as a force on its sign-adjusted output and multiplies by the closestToQuaternion sign. When the source chooses -q, this forwarding reverses every scalar consumer's atomic force, making an output-only option affect dynamics. Forward through an API that applies a derivative with respect to raw q, or compensate for the source sign before calling apply_force().

  if (has_precomputed_cvc("orientation")) {
    get_orientation_cvc()->apply_force(force.real_value * dx_dq);

• Files reviewed: 23/23 changed files
• Comments generated: 4
• Review effort level: Balanced

---

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

[giacomofiorin]

In one of the recent commits I work around the race condition in SMP parallelism (also correctly identified by the AI). Putting it up for review.

Note: I have not added documentation changes, since I'd first like feedback on the reuseComponent keyword and the way of referencing the component, using a fully-qualified name reuseComponent <colvar_name>/<cvc_name>. This looks a bit clunky, but we're still far from being able to define CVCs globally, and referencing them in colvar objects by name.

[Copilot]

Copilot review overview

🟡 Changes recommended

Reused rotations currently have initialization, scheduling, and force-sign correctness defects.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 4 · 2

Open (6)

• Regenerate golden output with Colvars SMP disabled · New
• Regenerate restart output with Colvars SMP disabled · New
• Avoid constructing derivative with uninitialized position counts · New
• This reference does not establish any scheduling dependency on the source colvar. If the source has…
• Assign component names before setup diagnostics · New
• Reject only unsupported SMP scheduling modes · New

Resolved since last review (2)

• Forwarding an orientation force directly only works when the reusing and source components choose…
• GPU mode is still accepted here, but reused CVCs have no atom groups of their own. The GPU…

[HanatoK]

Why are these functions moved to the .cpp file? I expect them to be inlined and can be used in future GPU porting.

[giacomofiorin]

You're right: they probably belong in a *_impl.h header though.

[HanatoK]

A single parent name seems strange. What would happen if the CVC has multiple parents? Are we going to reuse the whole CVCs, or only reuse some specific computational details (like q in some of them) of a few specific CVCs?

[HanatoK]

If so, then is debugGradients on still possible?

[HanatoK]

std::unordered_map might have better performance.

[giacomofiorin]

@HanatoK at the moment I'm simply trying to keep this branch up to date. I'm going to test out the "Watch and Fix" Copilot feature, so that it keeps an eye out for merge conflicts as more PRs are merged into master.