.. nvtools documentation master file, created by
   sphinx-quickstart on Sun Jun 30 10:48:04 2024.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to nvtools's documentation!
===================================

.. toctree::
   :maxdepth: 1
   :caption: Contents:


General usage
^^^^^^^^^^^^^
This library contains helper functions for plotting and analyzing ODMR spectra of nitrogen-vacancy centers in diamond.
The typical usage consists of loading a spectrum, fitting a model function and calculating the magnetic field from the
fitted resonances.

Global variables can be set to customize different behaviour.

.. code-block:: python

   from nvtools.io import H5Loader
   from nvtools.plot import ODMRPlotter


   def main():
       data = H5Loader().load_odmr_lia()
       ODMRPlotter().plot_from_spectrum(data.mw_frequency, data.observables["X"]["20"])


   if __name__ == "__main__":
       main()


Units and uncertainties
^^^^^^^^^^^^^^^^^^^^^^^
**nvtools** uses the Python packages `pint <https://pint.readthedocs.io/en/stable/>`_ and
`uncertainties <https://pythonhosted.org/uncertainties/index.html>`_ to deal with physical units and error propagation
wherever possible.

Here is a quick example to get you started, but be sure to check out their documentation to understand how to deal
with units and error values!

.. code-block:: python

   from nvtools import unit

   # pint units
   length = 5.3 * unit.meter                       # value with unit
   print(length.to("cm"))                          # = 530cm convert to different unit
   print(length.magnitude)                         # = 5.3 remove unit

   # uncertainties errors
   length = (5.3 * unit.meter).plus_minus(0.1)     # value with unit and error
   print(length.magnitude.nominal_value)           # = 5.3 value without unit and error
   print(length.magnitude.std_dev)                 # = 0.1 error of value without unit


Default values
^^^^^^^^^^^^^^
The default values for the D and E splitting and the gyromagnetic ratio are

.. math::
   D &= \SI{2870}{\mega\hertz}
.. math::
   E &= \SI{5}{\mega\hertz}
.. math::
   \gamma_{\text{NV}} &= \SI{28.032\pm0.004}{\mega\hertz\per\milli\tesla}

you can overwrite them if needed like so

.. code-block:: python

   import nvtools

   nvtools.D_SPLITTING = <new_value>
   nvtools.E_SPLITTING = <new_value>
   nvtools.GAMMA = <new_value>


Contents
--------

.. toctree::
   :maxdepth: 2

   modules/fit
   modules/io
   modules/plot
   modules/solver
   modules/symmetry
   modules/vector



Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`