.. _tutorials:

.. index:: tutorials

Tutorials
*********

Below (and in the ``examples`` folder on `GitLab <https://gitlab.com/materials-modeling/dynasor>`_) you can find several tutorials and examples that demonstrate how to use :program:`dynasor`.

In setting up these examples, suitable parameters were chosen for the MD simulations that provide physically sound (albeit not necessarily highly converged) results.
In practice, it is strongly recommended to carefully test the effect of e.g., system size, sampling time, spacing of snapshots, possibly interatomic potential/force field, and :program:`dynasor` averaging parameters.

The basics
==========

To begin with, there are two tutorials that deal with dynamics of :doc:`liquid <aluminum_liquid_dynamic>` and :doc:`solid aluminum <aluminum_solid_dynamic>`, respectively.
Here you can learn the basics, such as setting up a trajectory, setting up the q-points to sample (along a path in the solid case and spherically averaged in the liquid case), running a :program:`dynasor` calculation, understanding the contents of a :program:`dynasor`-sample, and some basic visualization of the results.

.. toctree::
   :caption: The basics
   :hidden:
   :maxdepth: 1

   aluminum_liquid_dynamic
   aluminum_solid_dynamic

Advanced applications
=====================

These tutorials cover some more advanced topics, such as splitting structure factors by species, some convergence considerations, and spectral energy density calculations.

In the tutorial on :doc:`ordered and disordered NiAl <NiAl-ordered-and-disordered>` you can learn how to handle multi-component systems by computing full and partial dynamic structure factors and current correlation for ordered and disordered NiAl.

In the :doc:`static structure tutorial <static_structure_factor>` you can learn how to compute the partial static structure factors for the different components of a halide perovskite and study the convergence of the results with system size and trajectory length.

The tutorial on the :doc:`spectral energy density (SED) <sed>` demonstrates how the latter can be calculated from a molecular dynamics simulation.
Afterwards the SED, which captures the full anharmonicity, is compared to a phonopy dispersion, which is based on harmonic lattice dynamics.

.. toctree::
   :caption: Advanced applications
   :hidden:
   :maxdepth: 1

   NiAl-ordered-and-disordered
   static_structure_factor
   sed


Post-processing
===============

In these tutorials you can learn about ways to post-process the :program:`dynasor` results, for example :doc:`weighting of structure factors with form factors <NiAl-neutron-and-Xray-weighting>` to compare with different scattering experiments, or extracting phonon frequencies and lifetimes by :doc:`peak fitting <dho_peak_fitting>` using the damped harmonic oscillator model.

.. toctree::
   :caption: Post-processing
   :hidden:
   :maxdepth: 1

   NiAl-neutron-and-Xray-weighting
   dho_peak_fitting


Other topics
============
It can be useful to analyze the dynamics of the atoms in terms of normal modes.
The normal modes behave roughly as independent harmonic oscillators for most materials.
It is thus possible to reason about these degrees of freedom as each having a single frequency and lifetime.
Even for very anharmonic materials normal modes can serve as an intuitive basis for further analysis.
In the :doc:`mode projection tutorial <mode_projection>` the basic functionality of :class:`dynasor.ModeProjector` is demonstrated.

The :doc:`ACF and FFTs tutorial <acfs_and_ffts>` provides some general insights into auto-correlation functions, Fourier transforms, and numerical tools for decreasing noise.

It is crucial to analyze convergence of the results, which is illustrated for the case of the convergence with respect to simulation time in :doc:`this tutorial <time_convergence>`.

.. toctree::
   :caption: Other topics
   :hidden:
   :maxdepth: 1

   mode_projection
   acfs_and_ffts
   time_convergence
