.. _examples-minimal: A minimal input file ==================== This is the shortest complete |pyretis| simulation: a RETIS run of a single particle in a double well, written with **no optional settings at all**. Every line of the input describes the physics of the problem. Everything else -- the move set, how the first paths are made, the output frequencies, the path-length cap, the simulation box -- is filled in by |pyretis|. Start here if you want to see what |pyretis| genuinely needs to be told before you meet the full :ref:`input description `. **Verification status:** passing -- see :ref:`example-tutorial-map`. Tutorial quick start -------------------- * **Best starting point:** :file:`examples/tutorials/path_sampling/internal/1D-double-well/minimal/`. * **Edit first:** :file:`minimal.toml`. * **Run:** ``pyretis run -i minimal.toml -p`` (about a minute). * **Analyse:** ``pyretis analyse -i minimal.toml``. * **Expected output:** numbered ensemble folders (``000``, ``001``, ...), ``pyretis.log``, ``output.toml``, and a ``report/`` folder after the analysis. The whole input file -------------------- .. literalinclude:: ../../examples/tutorials/path_sampling/internal/1D-double-well/minimal/minimal.toml :language: toml That is the complete input. The only other file the run needs is the starting configuration it points at, :file:`initial.xyz`, which holds one particle at :math:`x = -1`, the bottom of the left-hand well: .. literalinclude:: ../../examples/tutorials/path_sampling/internal/1D-double-well/minimal/initial.xyz Run it with: .. code-block:: pyretis pyretis run -i minimal.toml -p pyretis analyse -i minimal.toml Note that the analysis reads the **same input file** as the run, not the ``output.toml`` the run writes. What each section is for ------------------------ Only a handful of things cannot be guessed, because each one *is* the problem you are posing: ``potential`` The energy landscape: here the double well :math:`V(x) = a x^4 - b x^2 + c`, which has two stable states near :math:`x = \pm 1` separated by a barrier at :math:`x = 0`. :ref:`[simulation] ` What to run -- the ``retis`` task, how many Monte Carlo ``steps``, and the ``interfaces`` defining the path ensembles. The first and last interface mark the two states; the ones between them slice up the barrier region. :ref:`[system] ` That the system is one-dimensional, and the ``temperature`` it is sampled at. The temperature decides how rare the transition is, so it is a physical choice rather than a technical one. :ref:`[engine] ` How trajectories are propagated: Langevin dynamics with the given ``timestep`` and friction ``gamma``. ``[particles.position]`` Where the system starts, read from :file:`initial.xyz`. :ref:`[orderparameter] ` How progress along the reaction is measured -- here simply the position of the particle, which is what the interfaces are placed on. What |pyretis| fills in ----------------------- Everything a longer input would spell out is defaulted. The ones that matter most for this run: .. table:: Settings this input leaves to |pyretis|. :class: table-striped table-hover +-----------------------------+---------------------------------------------+ | Setting | Default used here | +=============================+=============================================+ | ``[initial-path] method`` | ``kick`` -- the first paths are generated by| | | kicking off the configuration you supply. | +-----------------------------+---------------------------------------------+ | ``[tis] maxlength`` | ``20000`` steps: a deliberately generous cap| | | on how long a trajectory may become. | +-----------------------------+---------------------------------------------+ | ``[tis] shooting_move`` | ``sh`` -- ordinary one-point shooting. | +-----------------------------+---------------------------------------------+ | ``[retis]`` | The standard swap and null-move frequencies.| +-----------------------------+---------------------------------------------+ | ``[output]`` | Sensible file-writing frequencies. | +-----------------------------+---------------------------------------------+ | ``[box]`` | A non-periodic box around the 1D system. | +-----------------------------+---------------------------------------------+ The keyword pages linked above (:ref:`[tis] `, :ref:`[retis] `, :ref:`[output] `, :ref:`[box] `, :ref:`[initial-path] `) document each default and when you would want to override it. Every setting a run actually used is written to ``output.toml`` when the run starts, so after a run you have the fully resolved version of the file you wrote. That is where to look when you want to know what a default resolved to, and what to copy from when you start pinning settings down explicitly. .. note:: Two of these defaults are physical rather than cosmetic, so it is worth knowing they are there. ``maxlength`` caps how long a trajectory may become; paths that reach the cap are rejected, and a cap that is *too small* biases the sampling. That is why the default is generous rather than tight -- but for a system with genuinely long paths you should still set it deliberately. ``temperature`` defaults to ``1.0`` when it is left out. For a rare-event simulation that is almost never what you want, which is why this tutorial sets it explicitly. This run is deliberately short (100 steps) so it finishes in about a minute. The rate constant it produces is therefore only indicative; raise ``steps`` for statistics you would report. Where to go next ---------------- * :ref:`RETIS in a 1D potential ` builds the same simulation the long way, explaining each section as it is added -- the natural next step once this run works. * The :ref:`input description ` lists every section and keyword together with its default. * :ref:`Analysing the output ` explains what lands in the ``report/`` folder.