Patchy Particle Prototyper in Python

p4 is a package for creating and analyzing models of particles and their interactions, based on HOOMD-blue and Plotly. Users can measure energy, force, and torque fields created by rigid bodies of particles interacting via pairwise potentials, and then interactively plot those bodies and fields in 3D, 2D, or 1D.

p4 has three objectives:

  1. to make it easy to see the effective shape of a rigid body’s interaction fields, rather than inferring it from simulation results;

  2. to make it easy to share rigid body models and interaction models without requiring specific software; and

  3. to make it easier to use HOOMD-blue for patchy particle systems research.

p4 accomplishes these objectives through an API that is designed to be

  • declarative, enabling easy serialization/deserialization to/from JSON;

  • comprehensive, accommodating arbitrary combinations of HOOMD-blue pair potentials; and

  • interactive, providing a rich plotting interface for rigid body models and fields.

How to Use this Documentation

Select the section that best applies to you.

I am learning how to use HOOMD-blue.

p4 will help you learn HOOMD-blue. p4’s API is much simpler and more beginner-friendly, and most of p4’s classes can be directly converted to HOOMD-blue equivalents.

Attention

In p4, interactions are currently confined to HOOMD-blue’s Molecular Dynamics (MD) module, so if you are only interested in Monte Carlo methods then p4 will not be as helpful to you.

Start by installing p4, and then read the following sections of the User Guide. They will help you understand the purpose and function of p4’s core classes.

  1. Specifying Particle Models covers the Body class, which corresponds to HOOMD-blue’s rigid constraint.

  2. Specifying Interaction Models covers the Interaction class, which corresponds to HOOMD-blue’s MD pair potential.

  3. Measuring Fields Around a Body covers the System and Field classes, which have no equivalents in HOOMD-blue.

  4. Measuring Fields Around Multiple Bodies covers the Arrangement class, which corresponds to HOOMD-blue’s Snapshot.

To learn more about the relationship between p4 and HOOMD-blue, read the section Creating HOOMD-blue objects from p4.

I want to use p4 in a current HOOMD-blue project.

Read Quickstart. It will guide you through p4’s core workflow beginning from an existing HOOMD-blue simulation in only a few minutes.

Next, read Accelerating Workflows, which will show you ways to integrate p4 into existing HOOMD-blue workflows. If you use Signac, that page also covers p4-Signac integration.

Afterwards, if you want to learn more about p4’s design and the functions of its various classes, read through the User Guide, starting with Specifying Particle Models.

Um… what?

Welcome! If you’d like to learn more about p4’s goals and motivation, read Project Goals.

If you are not a programmer, still take a look at the User Guide—all of the plots are interactive!

If you are a programmer and you are curious about p4’s codebase, read For Developers.