.. _examples-explore:

Exploring the order parameter (explore task)
============================================

This example shows the ``explore`` task on the 1D double well. An
exploratory run wanders the order-parameter space **without** enforcing
interface conditions, so it is a convenient first step when you do not
yet know a good order parameter or where to place the interfaces. The
visited order-parameter range and the generated trajectories then guide
interface placement for a subsequent TIS/RETIS run, and can be reused as
initial paths (see :ref:`Getting the initial path <user-guide-initial-paths>`).

**Verification status:** smoke -- see :ref:`example-test-status`.

Tutorial quick start
--------------------

* **Best starting point:**
  :file:`examples/tutorials/path_sampling/1D-double-well/explore/`.
* **Edit first:** ``task = "explore"`` and the ``interfaces`` list in the
  ``[simulation]`` section; the order parameter in ``[orderparameter]``.
* **Run:** ``pyretisrun -i explore.toml -p`` from the tutorial folder.
* **Expected output:** per-ensemble folders (``000``, ``001``, ...) with
  ``order.txt`` / ``energy.txt`` recording the explored order-parameter
  range; no crossing-probability analysis (an explore run is for
  scouting, not rate estimation).
* **Related check:** :file:`examples/tests/test-internal/explorer/`; see
  :ref:`example-test-status`.

Selecting the explore task
--------------------------

The ``explore`` task is requested in the
:ref:`simulation section <user-section-simulation>`; the rest of the
input is structured like an ordinary TIS run (interfaces, engine, order
parameter), and the initial configuration is provided through the usual
:ref:`initial-path section <user-section-initial-path>`:

.. literalinclude:: /_static/examples/explore1d/explore.toml
   :language: toml
   :start-at: [simulation]
   :end-before: [system]

Running the exploration
-----------------------

.. pyretis-collapse-block::
   :heading: Show/hide the full input file

   .. literalinclude:: /_static/examples/explore1d/explore.toml
      :language: toml

The initial configuration
:download:`initial.xyz </_static/examples/explore1d/initial.xyz>`
ships in the tutorial folder. Run with:

.. code-block:: pyretis

   pyretisrun -i explore.toml -p

Tested by
---------

The explore task is represented by
:file:`examples/tutorials/path_sampling/1D-double-well/explore/` (in the
tutorial smoke suite) and checked numerically by
:file:`examples/tests/test-internal/explorer/`.