Mixed patchy particle system

[hyper-aperiodic]

Hi, I'm trying to build a system with multiple (but different) 3-patch particles - for example: one particle with AAB patches, another with ABB. Like-like is attractive, like-unlike repulsive.

I'm aware I can't do this with AngularStep, and most legacy advice I have read suggests building a sim with rigid bodies. My issue is that a) I would like the potential on the particles to be highly directional, b) I would want the particles acting as patches to overlap.

I can't seem to wrap my head around how to do this - is it a case of using the anisotropic pair potential?

TIA!

[joaander]

You are correct, AngularStep makes no distinction between like-like and like-unlike for individual elements in the mask. However, the isotropic potential that it multiplies does. I think you could use Union to achieve the behavior you describe, though it is a bit convoluted. You need 4 particle types (A, B, P1, P2). Use e.g. a step potential between A and B to implement the like-like and like-unlike interactions. Use that as the isotropic potential with AngularStep to implement only 1 directional patch on each of A and B. Due to the way HOOMD-blue handles particle types, you also need to set interaction parameters for P1, P2, and all the cross terms involving P1 and P2 (even if they are 0) for Step and AngularStep. Then create a Union with the angular step as the constituent_potential and configure P1 to have the AAB patches - they could all be at the origin or offset from it depending on the model. The key thing is that the orientation of the particle in the union will direct the patch. Then do the same for P2 with its ABB patches. The union potential is the only one that acts on your system directly.

You could also to write a C++ component that implements the desired behavior in one step. You could base it on the AngulerStep code and modify accordingly. Unfortunately, this requires a moderate amount of boilerplate: https://github.com/glotzerlab/hpmc-energy-template/ should get you started.

I'm working on a new code that makes this type of customization as easy as writing a single function with no complex boilerplate, Python bindings, or dict unpacking required. That code isn't quite ready to share yet. I will announce it on this discussion board when it is. I plan to write a patchy particle tutorial for it. I am interested to see whether the Union approach or the direct evaluation is cleaner for multi-patch particles like this.

[hyper-aperiodic]

Hi Joshua,

Back again - I've tried in vain to go for the Union method, but have come up short. I've attached a minimal example for one patch on one type of particle. The P1s do not overlap as expected, but I see no stickiness. I'm aware it's probably a simple solution, but can't get my head round it. TIA!

import hoomd
import hoomd.hpmc
import numpy as np

device = hoomd.device.CPU()
sim = hoomd.Simulation(device=device)

snap = hoomd.Snapshot()

epsilon = 10
lambda_ = 5
sigma = 0.5
delta = np.pi/4
L = 2
kT = 0.5

snap.configuration.box = [L, L, 0, 0, 0, 0]
snap.particles.N = 4
snap.particles.types = ['P1', 'A']
snap.particles.position[:] = [(0, 0, 0), (.5, 0, 0), (0, .5, 0), (.5, .5, 0)]
snap.particles.typeid[:] = [0, 0, 0, 0]  # All P1 for now

sim.create_state_from_snapshot(snap)

step = hoomd.hpmc.pair.Step()
step.params[("A", "A")] = dict(epsilon=[-epsilon], r=[lambda_ * sigma])

for t1 in ['A', 'P1']:
    for t2 in ['A', 'P1']:
        if (t1, t2) not in step.params:
            step.params[(t1, t2)] = dict(epsilon=[0.0], r=[0.0])

step.params[('P1', 'P1')] = dict(epsilon=[1], r=[.5])

onePatch = hoomd.hpmc.pair.AngularStep(isotropic_potential=step)
ang = [(np.cos(0), np.sin(0), 0)]  # One patch direction

onePatch.mask["A"] = dict(directors=ang, deltas=[delta])
onePatch.mask["P1"] = dict(directors=[], deltas=[])


union = hoomd.hpmc.pair.Union(constituent_potential=onePatch)
union.body["P1"] = dict(
    types=["A"],
    positions=[(0, 0, 0)],
)
union.body["A"] = None

mc = hoomd.hpmc.integrate.Sphere(kT=kT)
mc.shape["P1"] = dict(diameter=sigma, orientable = True)  # point particle, zero hard core
mc.shape["A"] = dict(diameter=0)
mc.dimension = 2

mc.pair_potential = [union]

sim.operations.integrator = mc
sim.seed = 42
sim.run(10000)

[joaander]

Can you edit your post to format the code in a code block (see https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)? It is very hard to read code written in a variable width font interspersed with massive H1 headings taking the place of comments.

[hyper-aperiodic]

updated now - thank you for the help so far!

[joaander]

Thanks, that is much easier to read.

Try: mc.pair_potentials = [union] where you have mc.pair_potential = [union] (note the s).

According to the Python developers, it is a "feature" not a BUG that the language allows callers to create new attributes on types -- even if the user meant to set the value of an existing attribute.

[hyper-aperiodic]

aha - now my patches are sticking! fantastic that an extra s solves all. thanks again joshua :)

[hyper-aperiodic]

Hi Joshua, Thank you so much for the detailed reply, I'll be sure to try out union as it might be the quickest route for me. I'm happy (in a way) that it wasn't a simple question! Cheers!

…

On Mon, Jul 21, 2025, 11:32 PM Joshua A. Anderson ***@***.***> wrote: You are correct, AngularStep makes no distinction between like-like and like-unlike for individual elements in the mask. However, the isotropic potential that it multiplies does. I think you could use Union <https://hoomd-blue.readthedocs.io/en/v5.3.1/hoomd/hpmc/pair/union.html> to achieve the behavior you describe, though it is a bit convoluted. You need 4 particle types (A, B, P1, P2). Use e.g. a step potential between A and B to implement the like-like and like-unlike interactions. Use that as the isotropic potential with AngularStep to implement only 1 directional patch on each of A and B. Due to the way HOOMD-blue handles particle types, you also need to set interaction parameters for P1, P2, and all the cross terms involving P1 and P2 (even if they are 0) for Step and AngularStep. Then create a Union with the angular step as the constituent_potential and configure P1 to have the AAB patches - they could all be at the origin or offset from it depending on the model. The key thing is that the orientation of the particle in the union will direct the patch. Then do the same for P2 with its ABB patches. The union potential is the only one that acts on your system directly. You could also to write a C++ component that implements the desired behavior in one step. You could base it on the AngulerStep code and modify accordingly. Unfortunately, this requires a moderate amount of boilerplate: https://github.com/glotzerlab/hpmc-energy-template/ should get you started. I'm working on a new code that makes this type of customization as easy as writing a single function with no complex boilerplate, Python bindings, or dict unpacking required. That code isn't quite ready to share yet. I will announce it on this discussion board when it is. I plan to write a patchy particle tutorial for it. I am interested to see whether the Union approach or the direct evaluation is cleaner for multi-patch particles like this. — Reply to this email directly, view it on GitHub <#2105 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AWMPWNWAB6SV4GNSZXYVHVD3JVS6RAVCNFSM6AAAAACCAAJFSWVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTGOBTHA4DOMY> . You are receiving this because you authored the thread.Message ID: ***@***.***>