BROWNIAN Package Extension For Self-Alignment

[jeremyaqp]

Summary

This PR provides an extension to the BROWNIAN package to include the Self-Alignment torque, a property displayed by active particles subject to differential drag first introduced in Shimoyama1996 and further studied in the dry active matter community (see a relevant review on the bottom of this PR).
This torque is implemented with a single fix, BROWNIAN/fix_propel_selfalign and is compatible with both dipole or quaternion orientations.

Related Issue(s)

Author(s)

Jeremy Fersula @ Sorbonne University
jeremy.fersula@sorbonne-universite.fr

Licensing

By submitting this pull request, I agree, that my contribution will be included in LAMMPS and redistributed under either the GNU General Public License version 2 (GPL v2) or the GNU Lesser General Public License version 2.1 (LGPL v2.1).

Artificial Intelligence (AI) Tools Usage

By submitting this pull request, I confirm that I did NOT use any AI tools to generate
all or parts of the code and modifications in this pull request.

Backward Compatibility

Implementation Notes

No part of Lammps is affected by this package extension. Serial and MPI builds of the binary have been tested using the regular Makefile and CMake, documentation build has been tested using the regular Makefile.

OS PRETTY_NAME : "Ubuntu 22.04.4 LTS"
Make version : 4.3
CMake version : 3.22.1
Python version : 3.10.12
Doxygen version : 1.9.1

Post Submission Checklist

• The feature or features in this pull request is complete
• Licensing information is complete
• Corresponding author information is complete
• The source code follows the LAMMPS formatting guidelines
• Suitable new documentation files and/or updates to the existing docs are included
• The added/updated documentation is integrated and tested with the documentation build system
• The feature has been verified to work with the conventional build system
• The feature has been verified to work with the CMake based build system
• Suitable tests have been added to the unittest tree.
• A package specific README file has been included or updated
• One or more example input decks are included

Further Information, Files, and Links

Relevant review on Self-aligning polar active matter

[Copilot]

Pull request overview

This PR extends the BROWNIAN package to include a self-alignment torque for active particles subject to differential drag. The implementation adds a new fix propel/selfalign command that supports both dipole and quaternion orientations for modeling self-aligning polar active matter.

Key Changes:

• New fix implementation (fix_propel_selfalign.cpp/.h) adding self-alignment torque τ = ζ(e × v)
• Documentation for the new fix with mathematical formulation and usage examples
• Two example input scripts demonstrating collective motion with dipole and quaternion modes

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
src/BROWNIAN/fix_propel_selfalign.h	Header file declaring the FixPropelSelfAlign class with dipole and quaternion mode support
src/BROWNIAN/fix_propel_selfalign.cpp	Implementation of self-alignment torque calculation for both orientation modes
doc/src/fix_propel_selfalign.rst	Documentation including syntax, physics description, and usage restrictions
examples/BROWNIAN/in.selfalign_collective_quat.run	Example demonstrating quaternion-based collective motion with ellipsoids
examples/BROWNIAN/in.selfalign_collective_dipole.run	Example demonstrating dipole-based collective motion with spheres

---

You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.

[akohlmey]

@jeremyaqp Thanks for your submission.
I've added some "technical" changes to integrate it more cleanly and follow LAMMPS conventions more closely.

Since the fix applies an alignment but not a propulsion, wouldn't it be more consistent to call it fix align/self?

[jeremyaqp]

@jeremyaqp Thanks for your submission. I've added some "technical" changes to integrate it more cleanly and follow LAMMPS conventions more closely.

Since the fix applies an alignment but not a propulsion, wouldn't it be more consistent to call it fix align/self?

Yes it may be, I went with propel/selfalign because alignment usually goes with self-propulsion and there was a fix propel/self , but we should prioritize clarity

[akohlmey]

@jeremyaqp are you going to apply the suggested rename of the fix (and file name docs etc.)?
We are closing in on the next LAMMPS feature release and if this gets ready by Monday evening, it will likely be included. Otherwise, it will take a few months until the next release. I expect the time until that release to be longer than usual due to non-GitHub commitments.

[jeremyaqp]

@akohlmey Thank you for the notification, I did the refactor to align/self and renamed files accordingly. Logs in examples/PACKAGES/brownian/align_self/ are technically out of date but nothing changed code-wise so it is probably ok

[jtclemm]

I checked the changes and everything looks good to me. Only one comment. In addition to the atom style bonus quaternion, there's also a traditional atom property atom->quaternion. Currently, I think this might only used by atom style sphere/bpm (which might be a simpler platform for spherical particles as it simplifies integration). Body particles also have quaternions.

I think either
(a) the documentation should specifically note that it does not support other atom styles with quaternions (sphere/bpm or body particles, tri/line)
or
(b) logic should be added to handle either type of quaternion. Supporting more atom styles is, of course, nicer.

E.g. see

lammps/src/compute_property_atom.cpp

Line 1371 in 777aacc

if (avec_ellipsoid) {

[akohlmey]

Only one comment. In addition to the atom style bonus quaternion, there's also a traditional atom property atom->quaternion

@jtclemm I think that task is overkill and out of scope for this pull request. The code has been just following the example of fix propel/self. If we update one, we also need to update the other. Thus I suggest you submit this as a feature request issue instead. Also, there should be some minimal example added when supporting additional atom styles or flags or similar.