A general model for frictional contacts in colloidal systems

[khofmann6]

Description

I added a new class of pair force (similar to aniso). Here the relative "surface" velocity of two interacting particles is calculated (only for spherical particles) and is used to calculated a frictional force which may depend on this relative velocity. I added three frictional contact models (constant. linear, and Coulomb-Newton).

For more details see the preprint: https://arxiv.org/abs/2507.16388

Motivation and context

Frictional contacts couple translational and rotational degrees of freedom, which may affect the collective behavior of, e.g., colloids under shear and chiral active matter. Deterministic frictional contact models on the colloidal scale are thermodynamically inconsistent. This proposed model, which is roughly equivalent to DPD for anisotropic potentials, solves this inconsistency with a additional pairwise stochastic term.

How has this been tested?

The code was used to create the data presented in: https://arxiv.org/abs/2507.16388

pytest are still missing
Detailed documentation is missing

Checklist:

• I have reviewed the Contributor Guidelines.
• I agree with the terms of the HOOMD-blue Contributor Agreement.
• My name is on the list of contributors (sphinx-doc/credits.rst) in the pull request source branch.
• I have summarized these changes in CHANGELOG.rst following the established format.

[joaander]

FYI, you can execute pre-commit run --all-files to automatically fix most of those errors. See this page for more information.

[github-actions]

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.

[joaander]

Sorry, I've been very busy. I will review this pull request soon.

[joaander]

Thanks! I have some change requests and suggestions to improve this code.

You also need to fix the errors in the documentation build. These instructions explain how to build the documentation locally. You can merge trunk-minor into your branch to fix some of the warnings, but there are several more warnings coming from your code.

[joaander]

You will also need to merge trunk-minor into this branch to use the updated CI infrastructure.

[khofmann6]

Thank you for the review. I addressed all requested changes and suggestions. Two quick questions:

1. I'm unsure if I removed the shape_type and set_shape related methods correctly. Could you review my removal of shape_type/set_shape, especially in the GPU code?

For example in "FrictionPairGPU.cuh" i changed :

// initialize extra shared mem
char* s_extra = (char*)(s_shape_params + ntypes);

to

char* s_extra = (char*)( ntypes);

Im not sure if that is correct. My CUDA knowledge is limited, and I want to be sure it's right.

2. I'm still receiving errors for the documentation, and I can't figure them out.

Thank you for your support.

[joaander]

Thanks for the updates! I've pushed a few comments that apply my other suggestions directly.

1. I'm unsure if I removed the shape_type and set_shape related methods correctly. Could you review my removal of shape_type/set_shape, especially in the GPU code?

For example in "FrictionPairGPU.cuh" i changed :

// initialize extra shared mem char* s_extra = (char*)(s_shape_params + ntypes);

to

char* s_extra = (char*)( ntypes);

Im not sure if that is correct. My CUDA knowledge is limited, and I want to be sure it's right.

This should be:

    char* s_extra = (char*)(s_params + num_typ_parameters);

so that the extra shared memory doesn't overlap with the other type parameters.

2. I'm still receiving errors for the documentation, and I can't figure them out.

I pushed a commit that calls inspect.cleandoc to fix this.