.. _user-section-engine: The Engine section ================== The ``engine`` section specifies the engine to use for the dynamics. .. pyretis-input-example:: engine .. code-block:: rst Engine ------ class = VelocityVerlet timestep = 0.002 In |pyretis|, the engines are used as numerical integrators for Newton's equations of motion. The different engines need different settings and this is specified in detail below for the different types: .. |engine_verlet| replace:: :ref:`Verlet ` .. |engine_langevin| replace:: :ref:`Langevin ` .. |engine_vverlet| replace:: :ref:`Velocity Verlet ` .. |engine_gromacs| replace:: :ref:`GROMACS ` .. |engine_cp2k| replace:: :ref:`CP2K ` .. |engine_lammps| replace:: :ref:`LAMMPS ` .. |engine_user| replace:: :ref:`User-defined ` .. _table-engine-types: .. table:: Supported engines in |pyretis| :class: table-striped table-hover +-------------------+------------------------------------------------------+ | Engine | Description | +===================+======================================================+ | |engine_verlet| | Internal engine, integrate using the Verlet scheme. | +-------------------+------------------------------------------------------+ | |engine_langevin| | Internal engine, stochastic dynamics. | +-------------------+------------------------------------------------------+ | |engine_vverlet| | Internal engine, integration using the Velocity | | | verlet scheme. | +-------------------+------------------------------------------------------+ | |engine_gromacs| | External engine, using GROMACS. | +-------------------+------------------------------------------------------+ | |engine_cp2k| | External engine, using CP2K. | +-------------------+------------------------------------------------------+ | |engine_lammps| | External engine, using LAMMPS. | +-------------------+------------------------------------------------------+ | |engine_user| | Internal/External engine, user-defined. | +-------------------+------------------------------------------------------+ .. _user-section-engine-verlet: The Verlet engine ----------------- The Verlet engine integrates the equations of motion according to the Verlet scheme. NB: Only MD is allowed for this scheme. The engine is selected by specifying the class ``Verlet`` and the time step: .. pyretis-input-example:: Engine :class-name: Verlet .. code-block:: rst Engine ------ class = Verlet # select Verlet integrator timestep = 0.002 # time step for the integration Keywords for the Verlet engine ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For the Verlet engine, the following keywords can be set: .. |verlet_class| replace:: :ref:`class ` .. |verlet_time| replace:: :ref:`timestep ` .. _table-verlet-keywords: .. table:: Keywords for the Verlet engine. :class: table-striped table-hover +----------------+---------------------------------------------------+ | Keyword | Description | +================+===================================================+ | |verlet_class| | Selects the Verlet engine. | +----------------+---------------------------------------------------+ | |verlet_time| | Defines the time step. | +----------------+---------------------------------------------------+ .. _user-section-engine-verlet-class: Keyword class ............. .. pyretis-keyword:: class Verlet :specific: yes The class selects the Verlet engine and it should be set to ``Verlet``. .. _user-section-engine-verlet-time: Keyword timestep ................ .. pyretis-keyword:: timestep float The ``timestep`` keyword defines the time step for the engine in **internal units**. Default: Not any. This keyword must be specified. .. _user-section-engine-velocity-verlet: The Velocity Verlet engine -------------------------- The Velocity Verlet engine integrates the equations of motion according to the Velocity Verlet scheme. The engine is selected by specifying the class ``VelocityVerlet`` and the time step: .. pyretis-input-example:: Engine :class-name: VelocityVerlet .. code-block:: rst Engine ------ class = VelocityVerlet # select Velocity Verlet integrator timestep = 0.002 # time step for the integration Keywords for the Velocity Verlet engine ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For the Velocity Verlet engine, the following keywords can be set: .. |vverlet_class| replace:: :ref:`class ` .. |vverlet_time| replace:: :ref:`timestep ` .. _table-vverlet-keywords: .. table:: Keywords for the Velocity Verlet engine. :class: table-striped table-hover +-----------------+---------------------------------------------------+ | Keyword | Description | +=================+===================================================+ | |vverlet_class| | Selects the Velocity Verlet engine. | +-----------------+---------------------------------------------------+ | |vverlet_time| | Defines the time step. | +-----------------+---------------------------------------------------+ .. _user-section-engine-vverlet-class: Keyword class ............. .. pyretis-keyword:: class VelocityVerlet :specific: yes The class selects the Velocity Verlet engine and it should be set to ``VelocityVerlet``. .. _user-section-engine-vverlet-time: Keyword timestep ................ .. pyretis-keyword:: timestep float The ``timestep`` keyword defines the time step for the engine in **internal units**. Default: Not any. This keyword must be specified. .. _user-section-engine-langevin: The Langevin engine ------------------- The engine is selected by specifying the class ``Langevin``. This is a stochastic (Brownian) integrator and a description of the implementation can be found in e.g. [1]_. The integrator is fully specified as follows: .. pyretis-input-example:: Engine :class-name: Langevin .. code-block:: rst Engine ------ class = Langevin # select Langevin integrator timestep = 0.002 # time step for the integration gamma = 0.3 # set gamma value, seed = 0 # set seed for random value generator used high_friction = False # are we in the high friction limit? Keywords for the Langevin engine ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For the Langevin engine, the following keywords can be set: .. |langevin_class| replace:: :ref:`class ` .. |langevin_time| replace:: :ref:`timestep ` .. |langevin_gamma| replace:: :ref:`gamma ` .. |langevin_seed| replace:: :ref:`seed ` .. |langevin_hf| replace:: :ref:`high_friction ` .. _table-langevin-keywords: .. table:: Keywords for the Langevin engine. :class: table-striped table-hover +------------------+-------------------------------------------------------+ | Keyword | Description | +==================+=======================================================+ | |langevin_class| | Selects the Langevin engine. | +------------------+-------------------------------------------------------+ | |langevin_time| | Which defines the time step. | +------------------+-------------------------------------------------------+ | |langevin_gamma| | Which defines the the friction parameter. | +------------------+-------------------------------------------------------+ | |langevin_seed| | Which defines a seed to use for the random number | | | generator. | +------------------+-------------------------------------------------------+ | |langevin_hf| | Which determines if we are in the high friction | | | limit or not. | +------------------+-------------------------------------------------------+ .. _user-section-engine-langevin-class: Keyword class ............. .. pyretis-keyword:: class Langevin :specific: yes The class selects the Langevin engine and it should be set to ``Langevin``. .. _user-section-engine-langevin-time: Keyword timestep ................ .. pyretis-keyword:: timestep float The ``timestep`` keyword defines the time step for the engine in **internal units**. Default: Not any. This keyword must be specified. .. _user-section-engine-langevin-gamma: Keyword gamma ............. .. pyretis-keyword:: gamma float This is the gamma parameter (:math:`\gamma`, see the :ref:`integration scheme `) for the Langevin integrator. Default: Not any. This keyword must be specified. .. _user-section-engine-langevin-seed: Keyword seed ............ .. pyretis-keyword:: seed integer The seed value is an integer that is used to seed the random number generator used for the stochastic integration. Default: The default seed is zero: ``seed = 0`` .. _user-section-engine-langevin-hf: Keyword high_friction ..................... .. pyretis-keyword:: high_friction boolean This keyword determines how the equations of motion are integrated. This is a boolean value and thus it can be set to ``True`` or ``False``: * If ``high_friction`` is ``True``, we are in the high friction limit and the equations of motion are integrated according to .. math:: \mathbf{r}(t + \Delta t) = \mathbf{r}(t) + \gamma \Delta t \mathbf{f}(t)/m + \delta \mathbf{r}, where :math:`\mathbf{f}(t)` is the deterministic force and the displacements (:math:`\delta \mathbf{r}`) are drawn from a normal distribution, * If ``high_friction`` is ``False``, we are in the low friction limit and the equations of motion are integrated according to .. math:: \mathbf{r}(t + \Delta t) = \mathbf{r}(t) + c_1 \Delta t \mathbf{v}(t) + c_2 \mathbf{a}(t) \Delta t^2 + \delta \mathbf{r}, where, .. math:: \mathbf{v}(r + \Delta t) = c_0 \mathbf{v}(t) + (c_1-c_2) \Delta t \mathbf{a}(t) + c_2 \Delta t \mathbf{a}(t+\Delta t) + \delta \mathbf{v}, and :math:`c_0 = \text{e}^{-\gamma \Delta t}`, :math:`c_1 = (1 - c_0) / ( \gamma \Delta t)` and :math:`c_2 = (1 - c_1) / ( \gamma \Delta t)`. In this case, :math:`\delta \mathbf{r}` and :math:`\delta \mathbf{v}` are obtained as stochastic variables. Default: The default setting is ``high_friction = False`` .. _user-section-engine-gromacs: The GROMACS engine ------------------ The GROMACS engine will use GROMACS [2]_ in order to integrate the equations of motion. The engine is selected by specifying the class ``gromacs`` with some additional keywords: .. pyretis-input-example:: Engine :class-name: gromacs .. code-block:: rst Engine settings --------------- class = gromacs gmx = gmx mdrun = gmx mdrun input_path = gromacs_input timestep = 0.002 subcycles = 3 maxwarn = 0 write_vel = True write_force = False gmx_format = g96 Engine naming: the bare ``gromacs`` engine is now the **streaming** engine -- it reads the GROMACS output on the fly and runs faster than relaunching GROMACS for every order-parameter point. The slower relaunch-per-step engine is selected as ``gromacs_steps``. The former name ``gromacs2`` is a **deprecated** alias of ``gromacs`` (it still resolves to the streaming engine but emits a discontinuation warning). LAMMPS follows the same convention: ``lammps`` is the streaming engine and ``lammps_steps`` the relaunch-per-step one. Keywords for the GROMACS engine ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For the GROMACS engine, the following keywords can be set: .. |gmx_class| replace:: :ref:`class ` .. |gmx_gmx| replace:: :ref:`gmx ` .. |gmx_mdrun| replace:: :ref:`mdrun ` .. |gmx_input| replace:: :ref:`input_path ` .. |gmx_time| replace:: :ref:`timestep ` .. |gmx_sub| replace:: :ref:`subcycles ` .. |gmx_maxwarn| replace:: :ref:`maxwarn ` .. |gmx_write_vel| replace:: :ref:`write_vel ` .. |gmx_write_force| replace:: :ref:`write_force ` .. |gmx_gmx_format| replace:: :ref:`gmx_format ` .. |gmx_domain_dec| replace:: :ref:`domain_decomp ` .. |gmx_vel_gen| replace:: :ref:`velocity_generation ` .. _table-gromacs-keywords: .. table:: Keywords for the GROMACS engine. :class: table-striped table-hover +-------------------+------------------------------------------------------+ | Keyword | Description | +===================+======================================================+ | |gmx_class| | Selects the GROMACS engine. | +-------------------+------------------------------------------------------+ | |gmx_gmx| | Defines the command used to execute the GROMACS | | | ``gmx`` program. | +-------------------+------------------------------------------------------+ | |gmx_mdrun| | Defines the command used to execute the GROMACS | | | ``mdrun`` program. | +-------------------+------------------------------------------------------+ | |gmx_input| | Defines the folder containing the input to GROMACS. | +-------------------+------------------------------------------------------+ | |gmx_time| | Which defines the time step. | +-------------------+------------------------------------------------------+ | |gmx_sub| | Which defines the number of steps GROMACS will | | | execute before we calculate order parameters, i.e. | | | the frequency of output from GROMACS. | +-------------------+------------------------------------------------------+ | |gmx_maxwarn| | Which sets the ``-maxwarn`` option of GROMACS | | | grompp. | +-------------------+------------------------------------------------------+ | |gmx_write_vel| | Determines if velocities should be written by | | | GROMACS or not. | +-------------------+------------------------------------------------------+ | |gmx_write_force| | Determines if forces should be written by GROMACS or | | | not. | +-------------------+------------------------------------------------------+ | |gmx_gmx_format| | Can be used to select the format used for GROMACS | | | configurations. | +-------------------+------------------------------------------------------+ | |gmx_domain_dec| | Can be toggled on if domain decomposition is used | | | in GROMACS. | +-------------------+------------------------------------------------------+ | |gmx_vel_gen| | Selects how shooting velocities are drawn (the | | | engine's own generator or a Python Maxwell draw). | +-------------------+------------------------------------------------------+ .. _user-section-engine-gromacs-class: Keyword class ............. .. pyretis-keyword:: class gromacs :specific: yes The class selects the GROMACS engine and it should be set to ``gromacs``. ``gromacs`` is the **streaming** engine: it launches ``mdrun`` once per propagated path segment and reads the trajectory frames on the fly, stopping the run as soon as the path leaves the ensemble. This is the fast, recommended choice. The historical alias ``gromacs2`` selects the same engine and is kept for backward compatibility. For the slower **relaunch-per-step** engine — a fresh ``mdrun`` launch for every order-parameter point — set ``class = gromacs_steps``. The two engines integrate the same dynamics (see ``examples/tests/test-gromacs/test-integrate/``); prefer ``gromacs`` unless you specifically need the per-step relaunch behaviour. (Before this release the bare name ``gromacs`` selected the relaunch engine; it now selects the streaming engine — update old inputs to ``gromacs_steps`` if they relied on the previous behaviour.) .. _user-section-engine-gromacs-gmx: Keyword gmx ........... .. pyretis-keyword:: gmx string This keyword sets the command |pyretis| will use for executing the GROMACS ``gmx`` program. This can be used if you have different versions of GROMACS installed, for instance, a single precision build named ``gmx`` and a double precision build named ``gmx_d``. Default: Not any. This keyword must be specified. .. _user-section-engine-gromacs-mdrun: Keyword mdrun ............. .. pyretis-keyword:: mdrun string This keyword sets the command |pyretis| will use for executing the GROMACS ``mdrun`` program. This can be used to execute an MPI compiled version of ``mdrun``, by, for instance, setting: ``mdrun = mpiexec_mpt mdrun_mpi``. Note that this command is specific to the system you are using. Default: Not any. This keyword must be specified. .. _user-section-engine-gromacs-input: Keyword input_path .................. .. pyretis-keyword:: input_path string This keyword sets the directory where |pyretis| will look for input files to use with GROMACS. If, for instance, ``input_path = gromacs-input`` is set, then |pyretis| will look in the folder ``gromacs-input`` relative to the directory |pyretis| is executed in. Further, in the folder specified by ``input_path`` the following files **must** be present: - ``conf.g96``: The initial configuration. - ``grompp.mdp``: The simulation settings to use. Note that |pyretis| will alter the frequency of output and time step to match the setting given in the input to |pyretis| using the :ref:`timestep ` and :ref:`subcycles ` keywords. Effectively, |pyretis| will use ``grompp.mdp`` as a template and create a ``pyretis.mdp``, in the same folder, which is used for the GROMACS simulations. - ``topol.top``: The topology for your system. Default: Not any. This keyword must be specified. .. _user-section-engine-gromacs-time: Keyword timestep ................ .. pyretis-keyword:: timestep float The ``timestep`` keyword defines the time step for the engine in **internal units**, which in this case will be :ref:`gromacs units `. Default: Not any. This keyword must be specified. .. _user-section-engine-gromacs-sub: Keyword subcycles ................. .. pyretis-keyword:: subcycles integer The ``subcycles`` keyword defines the frequency of output from GROMACS and thus the frequency by which the order parameter(s) are obtained. Default: Not any. This keyword must be specified. .. _user-section-engine-gromacs-maxwarn: Keyword maxwarn ............... .. pyretis-keyword:: maxwarn integer The ``maxwarn`` keyword set the maximum number of warnings the GROMACS grompp command will ignore. Default: The default value is ``maxwarn = 0``. .. _user-section-engine-gromacs-write_vel: Keyword write_vel ................. .. pyretis-keyword:: write_vel boolean The ``write_vel`` keyword determines if GROMACS should write velocities when integrating the equations of motion. This can safely be set to ``False`` if your order parameter does not depend on the velocities. Default: The default value is ``write_vel = True``. .. _user-section-engine-gromacs-write_force: Keyword write_force ................... .. pyretis-keyword:: write_force boolean The ``write_force`` keyword determines if GROMACS should write forces when integrating the equations of motion. Typically, the forces are not needed unless your order parameter depends on them. Default: The default value is ``write_force = False``. .. _user-section-engine-gromacs-gmx_format: Keyword gmx_format .................. .. pyretis-keyword:: gmx_format string The ``gmx_format`` keyword specifies the format to use for GROMACS configurations. It can be set to ``gro`` or ``g96``. Default: The default value is ``gmx_format = gro``. .. _user-section-engine-gromacs-domain_decomp: Keyword domain_decomp ..................... .. pyretis-keyword:: domain_decomp boolean The ``domain_decomp`` keyword will execute ``gmx trjconv -pbc whole ...`` to a frame from which the system is propagated. This was implemented as some GROMACS versions did not handle bonds over periodic boundaries correctly. Default: The default value is ``domain_decomp = False``. .. _user-section-engine-gromacs-velocity_generation: Keyword velocity_generation ........................... .. pyretis-keyword:: velocity_generation string The ``velocity_generation`` keyword selects how the shooting velocities are drawn for a shooting move. With ``engine`` (the default) the velocities are produced by GROMACS itself; with ``maxwell`` they are instead drawn in Python from a Maxwell-Boltzmann distribution (the :py:meth:`draw_maxwellian_velocities ` helper, sharing the same reproducible random stream as the rest of the move). The default ``engine`` is byte-identical to earlier releases. ``maxwell`` additionally requires a ``temperature`` and the particle ``masses``, and the ``g96`` configuration format. Default: The default value is ``velocity_generation = engine``. .. _user-section-engine-cp2k: The ``CP2K`` engine ------------------- The CP2K engine will use CP2K [3]_ in order to integrate the equations of motion. The engine is selected by specifying the class ``cp2k`` with some additional keywords: .. pyretis-input-example:: Engine :class-name: cp2k .. code-block:: rst Engine ------ class = cp2k cp2k = cp2k input_path = cp2k-input timestep = 0.002 subcycles = 5 Engine naming: as for GROMACS and LAMMPS, the bare ``cp2k`` engine is now the **continuous** engine -- it runs CP2K as a single persistent process for a whole propagation segment and reads its trajectory on the fly (warm-starting the wavefunction from a per-ensemble ``.wfn`` restart), which is faster than relaunching CP2K for every order-parameter point. The slower relaunch-per-step engine, which chains the run through ``previous.restart`` / ``previous.wfn`` files, is selected as ``cp2k_steps``. Keywords for the CP2K engine ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For the CP2K engine, the following keywords can be set: .. |cp2k_class| replace:: :ref:`class ` .. |cp2k_cp2k| replace:: :ref:`cp2k ` .. |cp2k_input| replace:: :ref:`input_path ` .. |cp2k_time| replace:: :ref:`timestep ` .. |cp2k_sub| replace:: :ref:`subcycles ` .. _table-cp2k-keywords: .. table:: Keywords for the CP2K engine. :class: table-striped table-hover +--------------+-----------------------------------------------------------+ | Keyword | Description | +==============+===========================================================+ | |cp2k_class| | Selects the CP2K engine. | +--------------+-----------------------------------------------------------+ | |cp2k_cp2k| | Defines the command used to execute CP2K. | +--------------+-----------------------------------------------------------+ | |cp2k_input| | Defines the location of input files to use for CP2K. | +--------------+-----------------------------------------------------------+ | |cp2k_time| | Which defines the time step. | +--------------+-----------------------------------------------------------+ | |cp2k_sub| | Which defines the number of steps CP2K will execute | | | before we calculate order parameter(s). | +--------------+-----------------------------------------------------------+ .. _user-section-engine-cp2k-class: Keyword class ............. .. pyretis-keyword:: class cp2k :specific: yes The class selects the CP2K engine and it should be set to ``cp2k``. .. _user-section-engine-cp2k-cp2k: Keyword cp2k ............ .. pyretis-keyword:: cp2k string The command used for executing CP2K. Default: Not any. This keyword must be specified. .. _user-section-engine-cp2k-input: Keyword input_path .................. .. pyretis-keyword:: input_path string This keyword sets the directory where |pyretis| will look for input files to use with CP2K. If for instance ``input_path = cp2k-input`` is set, then |pyretis| will look in the folder ``cp2k-input`` relative to the directory |pyretis| is executed in. Further, in the folder specified by ``input_path`` the following files **must** be present: * ``initial.xyz``: A file with the initial configuration. * ``cp2k.inp``: A CP2K input file, defining a MD simulation. Default: Not any. This keyword must be specified. .. _user-section-engine-cp2k-time: Keyword timestep ................ .. pyretis-keyword:: timestep float The ``timestep`` keyword defines the time step for the engine in **internal units**. Default: Not any. This keyword must be specified. .. _user-section-engine-cp2k-sub: Keyword subcycles ................. .. pyretis-keyword:: subcycles integer The ``subcycles`` defines the frequency of the output from CP2K and thus the frequency by which the order parameter(s) are obtained. Default: Not any. This keyword must be specified. .. _user-section-engine-lammps: The ``LAMMPS`` engine --------------------- The LAMMPS engine will use LAMMPS [4]_ in order to integrate the equations of motion. A description of how to use the LAMMPS engine with |pyretis| can be found in :ref:`the user guide on LAMMPS `. The engine is selected by specifying the class ``lammps`` with some additional keywords: .. pyretis-input-example:: Engine :class-name: lammps .. code-block:: rst Engine ------ class = lammps lmp = lmp input_path = lammps_input subcycles = 1 extra_files = ['potential.in'] Keywords for the LAMMPS engine ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For the LAMMPS engine, the following keywords can be set: .. |lammps_class| replace:: :ref:`class ` .. |lammps_lmp| replace:: :ref:`lmp ` .. |lammps_input| replace:: :ref:`input_path ` .. |lammps_sub| replace:: :ref:`subcycles ` .. |lammps_extra| replace:: :ref:`extra_files ` .. |lammps_order_mode| replace:: :ref:`order_mode ` .. |lammps_vel_gen| replace:: :ref:`velocity_generation ` .. _table-lammps-keywords: .. table:: Keywords for the LAMMPS engine. :class: table-striped table-hover +----------------------+-----------------------------------------------------+ | Keyword | Description | +======================+=====================================================+ | |lammps_class| | Selects the LAMMPS engine. | +----------------------+-----------------------------------------------------+ | |lammps_lmp| | Defines the command used to execute LAMMPS. | +----------------------+-----------------------------------------------------+ | |lammps_input| | Defines the location of input files to use for | | | LAMMPS. | +----------------------+-----------------------------------------------------+ | |lammps_sub| | Which defines the number of steps LAMMPS will | | | execute before we calculate order parameter(s). | +----------------------+-----------------------------------------------------+ | |lammps_extra| | Defines the location of input files to use for | | | LAMMPS. | +----------------------+-----------------------------------------------------+ | |lammps_order_mode| | Selects whether order parameters are evaluated by | | | LAMMPS or by |pyretis|. | +----------------------+-----------------------------------------------------+ | |lammps_vel_gen| | Selects how shooting velocities are drawn (the | | | engine's own generator or a Python Maxwell draw). | +----------------------+-----------------------------------------------------+ .. _user-section-engine-lammps-class: Keyword class ............. .. pyretis-keyword:: class lammps :specific: yes The class selects the LAMMPS engine and it should be set to ``lammps``. ``class = lammps_steps`` is an explicit alias for the current relaunch-per-step LAMMPS engine (a fresh ``lmp`` launch for every order-parameter point). A streaming LAMMPS engine — analogous to the GROMACS ``gromacs`` engine — will become the canonical ``lammps`` once the engine base classes are unified; until then ``lammps`` and ``lammps_steps`` select the same relaunch engine. .. _user-section-engine-lammps-lmp: Keyword lmp ........... .. pyretis-keyword:: lmp string The command used for executing LAMMPS. Default: Not any. This keyword must be specified. .. _user-section-engine-lammps-input: Keyword input_path .................. .. pyretis-keyword:: input_path string This keyword sets the directory where |pyretis| will look for input files to use with LAMMPS. If for instance ``input_path = lammps_input`` is set, then |pyretis| will look in the folder ``lammps_input`` relative to the directory |pyretis| is executed in. Further, in the folder specified by ``input_path`` the following files **must** be present: * ``system.data``: A LAMMPS data file with the initial configuration. * ``lammps.in``: A LAMMPS input file, defining a MD simulation. * ``order.in``: A LAMMPS input file, defining the order parameter calculation. This file is required when ``order_mode = lammps`` and optional when ``order_mode = pyretis``. Default: Not any. This keyword must be specified. .. _user-section-engine-lammps-sub: Keyword subcycles ................. .. pyretis-keyword:: subcycles integer The ``subcycles`` defines the frequency of the output from LAMMPS, and thus the frequency by which the order parameter(s) are obtained. Default: Not any. This keyword must be specified. .. _user-section-engine-lammps-extra: Keyword extra ............. .. pyretis-keyword:: extra_files list of strings The ``extra_files`` defines additional files that might be needed to execute LAMMPS. For instance, may the user refer to several additional LAMMPS script in the given ``lammps.in`` file. This keyword is to make |pyretis| aware of these additional files. Default: None. .. _user-section-engine-lammps-order-mode: Keyword order_mode .................. .. pyretis-keyword:: order_mode string The ``order_mode`` keyword selects how order parameters and collective variables are evaluated for the LAMMPS engine. ``order_mode = lammps`` is the default. LAMMPS variables defined in ``order.in`` are printed by LAMMPS, and ``v_op_1`` is used by LAMMPS halt fixes to stop path propagation at the interfaces. ``order_mode = pyretis`` uses LAMMPS only for propagation. |pyretis| reads the dumped LAMMPS trajectory frames and evaluates the normal ``orderparameter`` and ``collective-variable`` sections in Python. In this mode, LAMMPS cannot halt directly on ``v_op_1``; |pyretis| truncates the generated path after evaluating the order parameter. Default: ``lammps``. .. _user-section-engine-lammps-velocity_generation: Keyword velocity_generation ........................... .. pyretis-keyword:: velocity_generation string The ``velocity_generation`` keyword selects how the shooting velocities are drawn for a shooting move. With ``engine`` (the default) the velocities are produced by LAMMPS itself; with ``maxwell`` they are instead drawn in Python from a Maxwell-Boltzmann distribution (the :py:meth:`draw_maxwellian_velocities ` helper, sharing the same reproducible random stream as the rest of the move). The default ``engine`` is byte-identical to earlier releases. ``maxwell`` requires a ``temperature`` (in LAMMPS ``real`` units). Default: The default value is ``velocity_generation = engine``. .. _user-section-engine-user-defined: User-defined engines -------------------- It is also possible to extend |pyretis| with user-defined engines, written in for instance Python, FORTRAN or C. User-defined engines are specified in Python modules that |pyretis| can load and they are typically specified as follows: .. _user-section-engine-user-example: .. pyretis-input-example:: Engine :class-name: a user-defined engine .. code-block:: rst Engine ------ class = VelocityVerletF module = vvengineF.py timestep = 0.002 Keywords for user-defined engines ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Typically, the user-defined engines requires that, at least, the following keywords are set: .. |custom_class| replace:: :ref:`class ` .. |custom_module| replace:: :ref:`module ` .. |custom_time| replace:: :ref:`timestep ` .. _table-keyword-user-engine: .. table:: Keywords for user-defined engines. :class: table-striped table-hover +-----------------+--------------------------------------------------------+ | Keyword | Description | +=================+========================================================+ | |custom_class| | Selects the engine. | +-----------------+--------------------------------------------------------+ | |custom_module| | Defines the Python file where the engine class is | | | defined. | +-----------------+--------------------------------------------------------+ | |custom_time| | Defines the timestep for the engine. | +-----------------+--------------------------------------------------------+ .. _user-section-engine-user-class: Keyword class ............. .. pyretis-keyword:: class string This keyword selects the engine and it should be set to the class name as it is defined in the given :ref:`module `. .. _user-section-engine-user-module: Keyword module .............. .. pyretis-keyword:: module string This keyword specified the location of the file containing the user-defined class. This file must be accessible by |pyretis|. Default Not any. This keyword must be specified. .. _user-section-engine-user-time: Keyword timestep ................ .. pyretis-keyword:: timestep float The ``timestep`` keyword defines the time step for the engine in **internal units**. Default: Not any. This keyword must be specified. Additional keywords ................... In addition, user-defined keywords can be specified, e.g.: .. pyretis-input-example:: Engine :class-name: a user-defined engine .. code-block:: rst Engine ------ class = VelocityVerletF module = vvintegratorf.py timestep = 0.002 keyword = 100 otherkeyword = 31 References ---------- .. [1] M. P. Allen and D. J. Tildesley, Computer Simulation of Liquids, 1989, Oxford University Press. .. [2] http://www.gromacs.org .. [3] https://www.cp2k.org/ .. [4] https://lammps.sandia.gov/