.. _examples-minimal-openmm: A minimal input file with an external engine ============================================ The :ref:`minimal input file ` tutorial uses |pyretis|' own internal integrator, so the input has to describe the system: the potential, the dimensionality, the starting configuration. With an **external engine** even that goes away. The engine already owns the system -- its particles, force field, box and starting configuration live in the engine's own input -- so |pyretis| only needs to be told three things: what to sample, which engine to drive, and how to measure progress along the reaction. This tutorial runs RETIS on two argon atoms with OpenMM. The whole simulation is defined by an OpenMM setup module plus the short input below. **Verification status:** passing -- see :ref:`example-tutorial-map`. Tutorial quick start -------------------- * **Best starting point:** :file:`examples/tutorials/path_sampling/openmm/argon-minimal/`. * **Requires:** the ``openmm`` Python package. * **Edit first:** :file:`minimal.toml`; edit :file:`openmm_sim.py` to change the physical system. * **Run:** ``pyretis run -i minimal.toml -p`` (under a minute). * **Analyse:** ``pyretis analyse -i minimal.toml``. The input file -------------- .. literalinclude:: ../../examples/tutorials/path_sampling/openmm/argon-minimal/minimal.toml :language: toml Where the system comes from --------------------------- Nothing in that file describes argon. The system is built by :file:`openmm_sim.py`, an ordinary OpenMM script that creates a ``Simulation`` object -- two argon atoms, a Lennard-Jones force, an integrator, and the starting positions and velocities: .. literalinclude:: ../../examples/tutorials/path_sampling/openmm/argon-minimal/openmm_sim.py :language: python The two ``[engine]`` keys ``openmm_module`` and ``openmm_simulation`` are what connect the two: they name the file to import and the variable inside it holding the ``Simulation``. |pyretis| then drives that object, which is why no ``[system]``, ``[particles]``, ``[potential]``, ``[forcefield]`` or ``[box]`` section appears in the input. What each section is for ------------------------ :ref:`[simulation] ` What to sample: the ``retis`` task, how many Monte Carlo ``steps``, and the ``interfaces`` -- placed on the order parameter below, in the engine's own units (nm here). :ref:`[engine] ` Which engine to drive and where its system comes from. The ``timestep`` is the OpenMM integrator's step size; the engine cross-checks it against the integrator and raises if they disagree, and the analysis needs it to express the rate per unit time. :ref:`[orderparameter] ` How progress is measured -- here the distance between the two atoms, which is what the interfaces are placed on. :ref:`[initial-path] ` The one initiation choice this system needs. The default builds each ensemble's first path by kicking off the starting configuration; for these interfaces a single kick cannot reach the outermost one, so ``kick-from = "previous"`` builds the ensembles up in turn instead. Everything else is defaulted exactly as in the :ref:`internal-engine tutorial `: the move set, the path-length cap, the output frequencies, the RETIS swap frequencies. Using a different external engine --------------------------------- The same shape applies to the other external engines -- GROMACS, LAMMPS and CP2K. Those read their system from an input *directory* rather than a Python module, so instead of ``openmm_module`` they take an ``input_path`` pointing at the engine's own input files. The rest of the input -- what to sample, how to measure it -- stays exactly as above. See the :ref:`engine section ` for the keys each engine takes. Where to go next ---------------- * :ref:`A minimal input file ` -- the same idea with |pyretis|' internal engine, where the input does define the system. * The :ref:`engine section ` documents every engine and its settings.