documentation and examples cleanup for fix propel/self

- rename example folder
- remove .txt format docs
- remove obsolete fix active sources
- update readme in src/USER-MISC
- replace non-ASCII characters and fix spelling issues

doc/src/fix.rst

@@ -308,6 +308,7 @@ accelerated styles exist.
 * :doc:`precession/spin <fix_precession_spin>` -
 * :doc:`press/berendsen <fix_press_berendsen>` - pressure control by Berendsen barostat
 * :doc:`print <fix_print>` - print text and variables during a simulation
+* :doc:`propel/self <fix_propel_self>` - model self-propelled particles
 * :doc:`property/atom <fix_property_atom>` - add customized per-atom values
 * :doc:`python/invoke <fix_python_invoke>` - call a Python function during a simulation
 * :doc:`python/move <fix_python_move>` -  call a Python function during a simulation run

doc/src/fix_propel_self.rst

@@ -38,19 +38,23 @@ Description
 Adds a force of a constant magnitude to each atom in the group. The nature in
 which the force is added depends on the mode.
 
-For mode = velocity, the active force acts along the velocity vector of each atom. This can
+For *mode* = *velocity*, the active force acts along the velocity vector of
-be interpreted as a velocity-dependent friction, such as proposed by :ref:`(Erdmann) <Erdmann>`.
+each atom. This can be interpreted as a velocity-dependent friction,
+such as proposed by :ref:`(Erdmann) <Erdmann>`.
 
-For mode = quaternion the force is along the axis obtained by rotating the x-axis along the
+For *mode* = *quaternion* the force is applied along the axis obtained
-atom's quaternion. In other words, the force is along the x-axis in the atom's body
+by rotating the x-axis along the atom's quaternion. In other words, the
-frame. This mode requires all atoms in the group to have a quaternion, so atom\_style should
+force is along the x-axis in the atom's body frame. This mode requires
-either be ellipsoid or body.  In combination with Langevin thermostat for translation and
+all atoms in the group to have a quaternion, so atom\_style should
-rotation in the overdamped regime, the quaternion mode corresponds to the active Brownian
+either be ellipsoid or body.  In combination with Langevin thermostat
-particle model introduced by :ref:`(Henkes) <Henkes>`, :ref:`(Bialke) <Bialke>` and :ref:`(Fily) <Fily>`.
+for translation and rotation in the overdamped regime, the quaternion
+mode corresponds to the active Brownian particle model introduced by
+:ref:`(Henkes) <Henkes>`, :ref:`(Bialke) <Bialke>` and :ref:`(Fily)
+<Fily>`.
 
-By default, this fix is applied to all atoms in the group. You can override this
+By default, this fix is applied to all atoms in the group. You can
-behavior by specifying the atom types the fix should work on through the *types*
+override this behavior by specifying the atom types the fix should work
-keyword.
+on through the *types* keyword.
 
 
 ----------
@@ -66,10 +70,10 @@ Restrictions
 """"""""""""
 
 
-In quaternion mode, this fix makes use of per-atom quaternions to take into account the fact
+In quaternion mode, this fix makes use of per-atom quaternions to take
-that the orientation can rotate and hence the direction of the active force can
+into account the fact that the orientation can rotate and hence the
-change. Therefore, the quaternion mode of this fix only works with atom\_styles that have a
+direction of the active force can change. The quaternion mode
-quaternion.
+of this fix only works with atom\_style ellipsoid.
 
 Related commands
 """"""""""""""""
@@ -80,7 +84,7 @@ Related commands
 
 
 
-**(Erdmann)** U. Erdmanna , W. Ebeling, L. Schimansky-Geier, and F. Schweitzer,
+**(Erdmann)** U. Erdmann , W. Ebeling, L. Schimansky-Geier, and F. Schweitzer,
 Eur. Phys. J. B 15, 105-113, 2000.
 
 .. _Henkes:
@@ -93,7 +97,7 @@ Eur. Phys. J. B 15, 105-113, 2000.
 
 
 
-**(Bialke)** J. Bialké, T. Speck, and H Löwen, Phys. Rev. Lett. 108, 168301, 2012.
+**(Bialke)** J. Bialke, T. Speck, and H Loewen, Phys. Rev. Lett. 108, 168301, 2012.
 
 .. _Fily:
 

doc/txt/fix_propel_self.txt

@@ -1,88 +0,0 @@
-"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
-
-:link(lws,http://lammps.sandia.gov)
-:link(ld,Manual.html)
-:link(lc,Section_commands.html#comm)
-
-:line
-
-fix propel/self command  :h3
-
-[Syntax:]
-
-fix ID group-ID propel/self mode magnitude keyword values ...
-
-ID, group-ID are documented in "fix"_fix.html command :ulb,l
-propel/self = style name of this fix command :l
-mode = velocity or quaternion :l
-magnitude = magnitude of the active force :l
-one or more keyword/value pairs may be appended to args :l
-keyword = {types} :l
-  {types} values = one or more atom types
-  
-:ule
-
-[Examples:]
-
-fix active_group all propel/self velocity 1.0
-fix constant_velocity all viscous 1.0 :pre
-
-fix active_group all propel/self quaternion 1.0 :pre
-
-fix active all propel/self quaternion 1.0 types 1 2 4 :pre
-
-
-[Description:]
-
-Adds a force of a constant magnitude to each atom in the group. The nature in
-which the force is added depends on the mode.
-
-For mode = velocity, the active force acts along the velocity vector of each atom. This can
-be interpreted as a velocity-dependent friction, such as proposed by "(Erdmann)"_#Erdmann.
-
-For mode = quaternion the force is along the axis obtained by rotating the x-axis along the
-atom's quaternion. In other words, the force is along the x-axis in the atom's body
-frame. This mode requires all atoms in the group to have a quaternion, so atom_style should
-either be ellipsoid or body.  In combination with Langevin thermostat for translation and
-rotation in the overdamped regime, the quaternion mode corresponds to the active Brownian
-particle model introduced by "(Henkes)"_#Henkes, "(Bialke)"_#Bialke and "(Fily)"_#Fily.
-
-By default, this fix is applied to all atoms in the group. You can override this
-behavior by specifying the atom types the fix should work on through the {types}
-keyword.
-
-:line
-
-[Restart, fix_modify, output, run start/stop, minimize info:]
-
-No information about this fix is written to "binary restart
-files"_restart.html.
-
-This fix is not imposed  during minimization.
-
-[Restrictions:]
-
-In quaternion mode, this fix makes use of per-atom quaternions to take into account the fact
-that the orientation can rotate and hence the direction of the active force can
-change. Therefore, the quaternion mode of this fix only works with atom_styles that have a
-quaternion.
-
-[Related commands:]
-
-"fix setforce"_fix_setforce.html, "fix addforce"_fix_addforce.html
-
-:link(Erdmann)
-[(Erdmann)] U. Erdmanna , W. Ebeling, L. Schimansky-Geier, and F. Schweitzer,
-Eur. Phys. J. B 15, 105-113, 2000.
-
-:link(Henkes)
-[(Henkes)] Henkes, S, Fily, Y., and Marchetti, M. C. Phys. Rev. E, 84, 040301(R), 2011.
-
-:link(Bialke)
-[(Bialke)] J. Bialké, T. Speck, and H Löwen, Phys. Rev. Lett. 108, 168301, 2012.
-
-:link(Fily)
-[(Fily)] Y. Fily and M.C. Marchetti, Phys. Rev. Lett. 108, 235702, 2012.
-
-
-[Default:] types

doc/utils/sphinx-config/false_positives.txt

@@ -220,6 +220,7 @@ Bext
 Bfrac
 bgq
 Bh
+Bialke
 Biersack
 bigbig
 bigint
@@ -691,6 +692,7 @@ eangle
 eatom
 Eb
 Eba
+Ebeling
 ebond
 ebook
 ebt
@@ -789,6 +791,7 @@ equilibration
 Equilibria
 equilization
 Ercolessi
+Erdmann
 eradius
 erate
 erc
@@ -879,6 +882,7 @@ filename
 Filename
 filenames
 Filenames
+Fily
 fileper
 filesystem
 Fincham
@@ -975,6 +979,7 @@ gcc
 gcmc
 gdot
 GeC
+Geier
 gencode
 georg
 Georg
@@ -1087,6 +1092,7 @@ Heenen
 Hendrik
 Henin
 Henkelman
+Henkes
 henrich
 Henrich
 Herrmann
@@ -1534,6 +1540,7 @@ lmptype
 ln
 localTemp
 localvectors
+Loewen
 logfile
 logfreq
 logicals
@@ -1598,6 +1605,7 @@ manpages
 manybody
 MANYBODY
 Maras
+Marchetti
 Marrink
 Marroquin
 Marsaglia
@@ -2093,6 +2101,7 @@ outfile
 outmost
 outputss
 Ouyang
+overdamped
 overlayed
 Ovito
 oxdna
@@ -2529,6 +2538,7 @@ scalexz
 scaleyz
 Schaik
 Schilfgarde
+Schimansky
 Schiotz
 Schlitter
 Schmid

src/USER-MISC/README

@@ -60,6 +60,7 @@ fix ipi, Michele Ceriotti (EPFL Lausanne), michele.ceriotti at gmail.com, 24 Nov
 fix npt/cauchy, R. E. Miller (Carleton University), F. Pavia and S. Pattamatta, 12 Jan 2020
 fix nvk, Efrem Braun (UC Berkeley), efrem.braun at gmail.com, https://github.com/lammps/lammps/pull/310
 fix pimd, Yuxing Peng (U Chicago), yuxing at uchicago.edu, 24 Nov 2014
+fix propel/self, Stefan Paquay (Brandeis U), stefanpaquay at gmail.com, 20 Jan 2020
 fix rhok, Ulf Pedersen (Roskilde U), ulf at urp.dk, 25 Sep 2017
 fix smd, Axel Kohlmeyer, akohlmey at gmail.com, 19 May 2008
 fix ti/spring, Rodrigo Freitas (Unicamp/Brazil), rodrigohb at gmail.com, 7 Nov 2013

src/USER-MISC/fix_active.cpp

@@ -1,163 +0,0 @@
-/* ----------------------------------------------------------------------
-   LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator
-   http://lammps.sandia.gov, Sandia National Laboratories
-   Steve Plimpton, sjplimp@sandia.gov
-
-   Copyright (2003) Sandia Corporation.  Under the terms of Contract
-   DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains
-   certain rights in this software.  This software is distributed under
-   the GNU General Public License.
-
-   See the README file in the top-level LAMMPS directory.
-   ------------------------------------------------------------------------- */
-
-/*  -----------------------------------------------------------------------
-   Contributed by Stefan Paquay @ Brandeis University
-
-   Thanks to Liesbeth Janssen @ Eindhoven University for useful discussions!
-   ----------------------------------------------------------------------- */
-
-
-#include <stdio.h>
-#include <string.h>
-
-#include "fix_active.h"
-
-#include "atom.h"
-#include "atom_vec_ellipsoid.h"
-#include "citeme.h"
-#include "comm.h"
-#include "error.h"
-#include "force.h"
-#include "group.h"
-#include "math.h"
-#include "math_const.h"
-#include "math_extra.h"
-#include "math_vector.h"
-#include "modify.h"
-#include "random_mars.h"
-#include "respa.h"
-#include "update.h"
-
-
-using namespace LAMMPS_NS;
-using namespace FixConst;
-using namespace MathConst;
-
-/*
-  Might be used later, who knows...
-static const char* cite_fix_active =
-  "fix active command:\n\n"
-  "@article{paquay-2018,\n"
-  "   author        = {Paquay, Stefan},\n"
-  "   doi           = {},\n"
-  "   issn          = {},\n"
-  "   journal       = {},\n"
-  "   month         = ,\n"
-  "   number        = ,\n"
-  "   pages         = ,\n"
-  "   title         = ,\n"
-  "   volume        = ,\n"
-  "   year          = \n"
-  "}\n\n";
-*/
-
-static constexpr const bool debug_out = false;
-
-FixActive::FixActive( LAMMPS *lmp, int narg, char **argv )
-  : Fix(lmp, narg, argv)
-{
-  // if( lmp->citeme) lmp->citeme->add(cite_fix_active);
-  if( narg < 4 ) error->all(FLERR, "Illegal fix active command");
-
-  AtomVecEllipsoid *av = static_cast<AtomVecEllipsoid*>(atom->avec);
-  if (!av) error->all(FLERR, "FixActive requires atom_style ellipsoid");
-
-  if( debug_out && comm->me == 0 ){
-    fprintf(screen, "This is fix active, narg is %d\n", narg );
-    fprintf(screen, "args:");
-    for( int i = 0; i < narg; ++i ){
-      fprintf(screen, " %s", argv[i]);
-    }
-    fprintf(screen, "\n");
-  }
-
-  // args: fix ID all active magnitude prop1 prop2 prop3
-  // Optional args are
-  magnitude = force->numeric( FLERR, argv[3] );
-}
-
-
-FixActive::~FixActive()
-{}
-
-
-int FixActive::setmask()
-{
-  int mask = 0;
-  mask |= POST_FORCE;
-
-  return mask;
-}
-
-
-double FixActive::memory_usage()
-{
-  double bytes = 0.0;
-  return bytes;
-}
-
-
-
-void FixActive::post_force(int /* vflag */ )
-{
-  // Then do the rest:
-  double **f = atom->f;
-
-  AtomVecEllipsoid *av = static_cast<AtomVecEllipsoid*>(atom->avec);
-
-  int *mask = atom->mask;
-  int nlocal = atom->nlocal;
-  if (igroup == atom->firstgroup) nlocal = atom->nfirst;
-
-  AtomVecEllipsoid::Bonus *bonus = av->bonus;
-  // Add the active force to the atom force:
-  for( int i = 0; i < nlocal; ++i ){
-    if( mask[i] & groupbit ){
-      double f_act[3] = { 0.0, 0.0, 1.0 };
-      double f_rot[3];
-
-      int* ellipsoid = atom->ellipsoid;
-      double *quat  = bonus[ellipsoid[i]].quat;
-      tagint *tag = atom->tag;
-
-      double Q[3][3];
-      MathExtra::quat_to_mat( quat, Q );
-      MathExtra::matvec( Q, f_act, f_rot );
-
-      if (debug_out && comm->me == 0) {
-        // Magical reference particle:
-        if (tag[i] == 12) {
-          fprintf(screen, "rotation quaternion: (%f %f %f %f)\n",
-                  quat[0], quat[1], quat[2], quat[3]);
-          fprintf(screen, "rotation matrix: / %f %f %f \\\n",
-                  Q[0][0] ,Q[0][1], Q[0][2]);
-          fprintf(screen, "                 | %f %f %f |\n",
-                  Q[1][0] ,Q[1][1], Q[1][2]);
-          fprintf(screen, "                 \\ %f %f %f /\n",
-                  Q[2][0] ,Q[2][1], Q[2][2]);
-
-          fprintf(screen, "Active force on atom %d: (%f %f %f)\n",
-                  tag[i], f_rot[0], f_rot[1], f_rot[2]);
-          fprintf(screen, "  Total force before: (%f %f %f)\n",
-                  f[i][0], f[i][1], f[i][2]);
-        }
-      }
-
-      f[i][0] += magnitude * f_rot[0];
-      f[i][1] += magnitude * f_rot[1];
-      f[i][2] += magnitude * f_rot[2];
-
-    }
-  }
-}

src/USER-MISC/fix_active.h

@@ -1,55 +0,0 @@
-/* -*- c++ -*- ----------------------------------------------------------
-   LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator
-   http://lammps.sandia.gov, Sandia National Laboratories
-   Steve Plimpton, sjplimp@sandia.gov
-
-   Copyright (2003) Sandia Corporation.  Under the terms of Contract
-   DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains
-   certain rights in this software.  This software is distributed under
-   the GNU General Public License.
-
-   See the README file in the top-level LAMMPS directory.
-------------------------------------------------------------------------- */
-
-#ifdef FIX_CLASS
-
-FixStyle(active,FixActive)
-
-#else
-
-#ifndef LMP_FIX_ACTIVE_H
-#define LMP_FIX_ACTIVE_H
-
-#include "fix.h"
-
-namespace LAMMPS_NS {
-
-class FixActive : public Fix {
- public:
-  FixActive(class LAMMPS *, int, char **);
-  virtual ~FixActive();
-  virtual int setmask();
-  virtual void post_force(int);
-  // virtual void post_force_respa(int, int, int);
-
-  double memory_usage();
-
-protected:
-  double magnitude;
-  int thermostat_orient;
-};
-
-}
-
-#endif
-#endif
-
-/* ERROR/WARNING messages:
-
-E: Illegal ... command
-
-Self-explanatory.  Check the input script syntax and compare to the
-documentation for the command.  You can use -echo screen as a
-command-line option when running LAMMPS to see the offending line.
-
-*/