comphy-lab · pull · Mar 26, 2026 · Dec 11, 2023 · Dec 11, 2023 · Dec 11, 2023
diff --git a/doc/src/Commands_pair.rst b/doc/src/Commands_pair.rst
@@ -112,6 +112,7 @@ OPT.
    * :doc:`gran/hooke (o) <pair_gran>`
    * :doc:`gran/hooke/history (ko) <pair_gran>`
    * :doc:`granular <pair_granular>`
+   * :doc:`granular/superellipsoid <pair_granular_superellipsoid>`
    * :doc:`gw <pair_gw>`
    * :doc:`gw/zbl <pair_gw>`
    * :doc:`harmonic/cut (o) <pair_harmonic_cut>`

diff --git a/doc/src/Howto_granular.rst b/doc/src/Howto_granular.rst
@@ -1,17 +1,21 @@
 Granular models
 ===============
 
-Granular systems are composed of spherical particles with a diameter, as
-opposed to point particles.  This means they have an angular velocity
-and torque can be imparted to them to cause them to rotate.
+Granular systems are typically composed of spherical particles with a diameter,
+as opposed to point particles.  This means they have an angular
+velocity and torque can be imparted to them to cause them to rotate.
 
-To run a simulation of a granular model, you will want to use
+To run a simulation of a granular model, you will typically want to use
 the following commands:
 
 * :doc:`atom_style sphere <atom_style>`
 * :doc:`fix nve/sphere <fix_nve_sphere>`
 * :doc:`fix gravity <fix_gravity>`
 
+Aspherical granular particles can be simulated by creating clusters of spherical
+particles using either the :doc:`rigid <fix_rigid>` or :doc:`BPM <Howto_bpm>`
+package or by using :doc:`superellipsoids <pair_granular_superellipsoid>`.
+
 This compute
 
 * :doc:`compute erotate/sphere <compute_erotate_sphere>`

diff --git a/doc/src/Howto_spherical.rst b/doc/src/Howto_spherical.rst
@@ -50,13 +50,16 @@ individual particles, after then are created.
 
 The ellipsoid style defines particles that are ellipsoids and thus can
 be aspherical.  Each particle has a shape, specified by 3 diameters,
-and mass (or density).  These particles store an angular momentum and
-their orientation (quaternion), and can be acted upon by torque.  They
-do not store an angular velocity (omega), which can be in a different
-direction than angular momentum, rather they compute it as needed.
-The "set" command can be used to modify the diameter, orientation, and
-mass of individual particles, after then are created.  It also has a
-brief explanation of what quaternions are.
+and mass (or density).  Superellipsoid particles can be defined by
+specifying 2 blockiness exponents (block) and adding the `superellipsoid`
+keyword to the `atom_style ellipsoid` command.  These particles store an angular
+momentum and their orientation (quaternion), and can be acted upon by
+torque.  They do not store an angular velocity (omega), which can be
+in a different direction than angular momentum, rather they compute it
+as needed.  The "set" command can be used to modify the diameter, orientation,
+and mass of individual particles, after they are created.
+The "set" command can also be used to modify the blockiness of superellipsoid
+particles. It also has a brief explanation of what quaternions are.
 
 The line style defines line segment particles with two end points and
 a mass (or density).  They can be used in 2d simulations, and they can
@@ -113,9 +116,11 @@ When a system with finite-size particles is defined, the particles
 will only rotate and experience torque if the force field computes
 such interactions.  These are the various :doc:`pair styles <pair_style>` that generate torque:
 
-* :doc:`pair_style gran/history <pair_gran>`
-* :doc:`pair_style gran/hertz <pair_gran>`
-* :doc:`pair_style gran/no_history <pair_gran>`
+* :doc:`pair_style granular <pair_granular>`
+* :doc:`pair_style gran/hooke <pair_gran>`
+* :doc:`pair_style gran/hooke/history <pair_gran>`
+* :doc:`pair_style gran/hertz/history <pair_gran>`
+* :doc:`pair_style granular/superellipsoid <pair_granular_superellipsoid>`
 * :doc:`pair_style dipole/cut <pair_dipole>`
 * :doc:`pair_style gayberne <pair_gayberne>`
 * :doc:`pair_style resquared <pair_resquared>`
@@ -126,7 +131,8 @@ such interactions.  These are the various :doc:`pair styles <pair_style>` that g
 * :doc:`pair_style body/nparticle <pair_body_nparticle>`
 
 The granular pair styles are used with spherical particles.  The
-dipole pair style is used with the dipole atom style, which could be
+*granular/superellipsoid* granular pair styles are used with superellipsoid particles.
+The dipole pair style is used with the dipole atom style, which could be
 applied to spherical or ellipsoidal particles.  The GayBerne and
 REsquared potentials require ellipsoidal particles, though they will
 also work if the 3 shape parameters are the same (a sphere).  The

diff --git a/doc/src/Packages_details.rst b/doc/src/Packages_details.rst
@@ -253,8 +253,8 @@ ASPHERE package
 
 **Contents:**
 
-Computes, time-integration fixes, and pair styles for aspherical
-particle models including ellipsoids, 2d lines, and 3d triangles.
+Computes, time-integration fixes, and pair styles for aspherical particle models
+including ellipsoids, granular superellipsoids, 2d lines, and 3d triangles.
 
 **Supporting info:**
 
@@ -265,6 +265,7 @@ particle models including ellipsoids, 2d lines, and 3d triangles.
 * :doc:`pair_style ylz <pair_ylz>`
 * :doc:`pair_style line/lj <pair_line_lj>`
 * :doc:`pair_style tri/lj <pair_tri_lj>`
+* :doc:`pair_style granular/superellipsoid <pair_granular_superellipsoid>`
 * `doc/PDF/pair_gayberne_extra.pdf <PDF/pair_gayberne_extra.pdf>`_
 * `doc/PDF/pair_resquared_extra.pdf <PDF/pair_resquared_extra.pdf>`_
 * ``examples/ASPHERE``

diff --git a/doc/src/atom_style.rst b/doc/src/atom_style.rst
@@ -28,6 +28,7 @@ Syntax
          *template* arg = template-ID
            template-ID = ID of molecule template specified in a separate :doc:`molecule <molecule>` command
          *hybrid* args = list of one or more sub-styles, each with their args
+         *ellipsoid* arg = superellipsoid (optional) for superellipsoids instead of ellipsoids
 
 * accelerated styles (with same args) = *angle/kk* or *atomic/kk* or *bond/kk* or *charge/kk* or *full/kk* or *molecular/kk* or *spin/kk*
 
@@ -354,6 +355,14 @@ quaternion 4-vector with its orientation.  Each particle stores a flag
 in the ellipsoid vector which indicates whether it is an ellipsoid (1)
 or a point particle (0).
 
+.. versionadded:: TBD
+
+By adding the flag *superellipsoid* to the *ellipsoid* atom_style
+command, the particles can be superellipsoids, which are a
+generalization of ellipsoids with two additional blockiness parameters
+that control the shape.  Superellipsoids also store the principal
+moments of inertia of the particle.
+
 For the *line* style, particles can be are idealized line segments
 which store a per-particle mass and length and orientation (i.e. the
 end points of the line segment).  Each particle stores a flag in the

diff --git a/doc/src/compute_property_atom.rst b/doc/src/compute_property_atom.rst
@@ -26,6 +26,8 @@ Syntax
                              temperature, heatflow,
                              angmomx, angmomy, angmomz,
                              shapex, shapey, shapez,
+                             block1, block2,
+                             inertiax, inertiay, inertiaz,
                              quatw, quati, quatj, quatk, tqx, tqy, tqz,
                              end1x, end1y, end1z, end2x, end2y, end2z,
                              corner1x, corner1y, corner1z,
@@ -64,6 +66,8 @@ Syntax
            *heatflow* = internal heat flow of spherical particle
            *angmomx,angmomy,angmomz* = angular momentum of aspherical particle
            *shapex,shapey,shapez* = 3 diameters of aspherical particle
+           *block1,block2* = 2 blockiness exponents of aspherical (superellipsoid) particle
+           *inertiax,inertiay,inertiaz* = 3 principal moments of inertia of aspherical (superellipsoid) particle
            *quatw,quati,quatj,quatk* = quaternion components for aspherical or body particles
            *tqx,tqy,tqz* = torque on finite-size particles
            *end12x, end12y, end12z* = end points of line segment
@@ -163,6 +167,20 @@ If :doc:`newton bond off <newton>` is set, it will be tallied with both atom
 The quantities *shapex*, *shapey*, and *shapez* are defined for ellipsoidal
 particles and define the 3d shape of each particle.
 
+.. versionadded:: TBD
+
+The quantities *block1*, and *block2*, are defined for superellipsoidal
+particles and define the blockiness of each superellipsoid particle.
+See the :doc:`set <set>` command for an explanation of the blockiness.
+
+.. versionadded:: TBD
+
+The quantities *inertiax*, *inertiay*, and *inertiaz* are defined for
+superellipsoidal particles and define the 3 principal moments of inertia
+of each particle.  These are with respect to the particle's center of
+mass and in a reference system aligned with the particle's principal
+axes.
+
 The quantities *quatw*, *quati*, *quatj*, and *quatk* are defined for
 ellipsoidal particles and body particles and store the 4-vector quaternion
 representing the orientation of each particle.  See the :doc:`set <set>`

diff --git a/doc/src/pair_granular.rst b/doc/src/pair_granular.rst
@@ -63,7 +63,7 @@ global, but can be set to different values for different combinations
 of particle types, as determined by the :doc:`pair_coeff <pair_coeff>`
 command.  If the contact model choice is the same for two particle
 types, the mixing for the cross-coefficients can be carried out
-automatically. This is shown in the last example, where model
+automatically. This is shown in one of the examples, where model
 choices are the same for type 1 - type 1 as for type 2 - type2
 interactions, but coefficients are different. In this case, the
 mixed coefficients for type 1 - type 2 interactions can be determined from