.. _sphx_glr_examples_intermediate:

Intermediate Examples
=====================

These examples assume familiarity with the basic tier and introduce
the storage layer, performance monitoring, and more complex pipeline
patterns.

**01 — Multi-Stage Pipeline**: FusedStage composition, LoggingHook CSV output,
step-budget migration, fused hooks for global status monitoring.

**02 — Trajectory I/O**: Writing trajectories to Zarr, reading back with
DataLoader, round-trip validation.

**03 — NPT MD**: Pressure-controlled dynamics with the MTK barostat,
LJ stress computation, cell fluctuation monitoring.

**04 — Inflight Batching**: SizeAwareSampler, Mode 2 FusedStage run (batch=None),
system_id tracking, ConvergedSnapshotHook collecting results.

**05 — Safety and Monitoring**: NaNDetectorHook, MaxForceClampHook,
EnergyDriftMonitorHook, ProfilerHook — defensive MD patterns.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates how to compose multiple dynamics stages into a single GPU-resident pipeline using FusedStage. A typical MD workflow chains geometry relaxation (FIRE) into equilibration (NVT) and then production sampling (NVE).  Running all three stages on a shared batch avoids repeated CPU–GPU data transfers between stages.">

.. only:: html

  .. image:: /examples/intermediate/images/thumb/sphx_glr_01_multistage_pipeline_thumb.png
    :alt:

  :doc:`/examples/intermediate/01_multistage_pipeline`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Multi-Stage Dynamics Pipelines with FusedStage</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Zarr is a chunked, compressed array format designed for large scientific datasets.  nvalchemi uses it as the on-disk representation for trajectories: each dynamics snapshot is serialised into a CSR-style layout (pointer arrays + concatenated fields) so that random-access reads and incremental appends are both efficient.">

.. only:: html

  .. image:: /examples/intermediate/images/thumb/sphx_glr_02_trajectory_zarr_io_thumb.png
    :alt:

  :doc:`/examples/intermediate/02_trajectory_zarr_io`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Writing and Replaying Trajectories with Zarr</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The NPT ensemble keeps temperature T and pressure P constant while letting the simulation cell fluctuate in response to the instantaneous virial stress.  This is the correct ensemble for studying phase transitions, equations of state, and crystal relaxations under applied pressure.">

.. only:: html

  .. image:: /examples/intermediate/images/thumb/sphx_glr_03_npt_variable_cell_thumb.png
    :alt:

  :doc:`/examples/intermediate/03_npt_variable_cell`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Pressure-Controlled (NPT) Molecular Dynamics</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The problem: a production relaxation campaign may require running thousands of structures through FIRE → NVT stages.  Loading all of them into GPU memory at once is impossible; processing one at a time wastes GPU throughput.">

.. only:: html

  .. image:: /examples/intermediate/images/thumb/sphx_glr_04_inflight_batching_thumb.png
    :alt:

  :doc:`/examples/intermediate/04_inflight_batching`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Processing Large Datasets with Inflight Batching</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Numerical instabilities are a fact of life in machine-learning molecular dynamics.  ML potentials are trained on a finite region of configuration space; geometries outside that region can produce enormous forces, NaN gradients, or energy drift that silently corrupts a long trajectory.">

.. only:: html

  .. image:: /examples/intermediate/images/thumb/sphx_glr_05_safety_and_monitoring_thumb.png
    :alt:

  :doc:`/examples/intermediate/05_safety_and_monitoring`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Defensive MD: Safety Hooks and Performance Monitoring</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:

   /examples/intermediate/01_multistage_pipeline
   /examples/intermediate/02_trajectory_zarr_io
   /examples/intermediate/03_npt_variable_cell
   /examples/intermediate/04_inflight_batching
   /examples/intermediate/05_safety_and_monitoring