Quick Start
===========

The generic workflow of the simulation includes first the generation of the spin bath in the material,
and second performing the CCE dynamics calculations for the qubit interacting with this spin bath.

Base units
----------

* All coupling constants are given in :math:`\mathrm{kHz}`.
* Timesteps are in millisecond (:math:`\mathrm{ms}`).
* Distances are in angstrom (:math:`\mathrm{A}`).
* Gyromagnetic ratios are given in :math:`\mathrm{rad}\cdot\mathrm{ms}^{-1}\cdot\mathrm{G}^{-1}`.
* Quadrupole constants are given in :math:`\mathrm{barn}` (:math:`10^{-28}\ \mathrm{m}^2`).
* Magnetic field is given in Gauss (:math:`\mathrm{G}`).

Simple example
--------------

The simplest example includes the following steps:

1. Generate the ``BathCell`` object.
   Here we use the interface with ``ase`` which can effortlessly generate unit cells of many
   materials. As an example, we import the diamond structure.

   .. literalinclude:: tutorials/nv_simple.py
      :language: python
      :lines: 1-5

2. Using the ``BathCell`` object, generate spin bath
   of the most common isotopes in the material. Here we generate the spin bath
   of size 200 Angstrom and remove one carbon, where the spin of interest is located, from the diamond crystal lattice.

   .. literalinclude:: tutorials/nv_simple.py
      :language: python
      :lines: 6

   This function returns the ``BathArray`` instance, which contains names of the bath spins in ``'N'``, their coordinates
   in angstrom in ``'xyz'``, empty arrays of hyperfine couplings in :math:`\mathrm{kHz}` in ``'A'``,
   and quadrupole couplings in :math:`\mathrm{kHz}` in ``'Q'`` namefields.
   The hyperfine couplings will be generated by ``Simulator`` in the next step. For alternative ways to define
   hyperfine couplings see :doc:`parameters`.

3. Setup the ``Simulator`` using the generated spin bath.
   The first required argument ``spin`` is the total spin of the central spin or the ``CenterArray`` instance,
   containing properties of the central spins.
   ``r_bath``, ``r_dipole`` and ``order`` are convergence parameters
   (see the :doc:`tutorial` for examples of convergence),
   ``magnetic_field`` is the external applied magnetic field along the z-axis,
   and ``pulses`` is the number of decoupling :math:`\pi` pulses in Carr-Purcell-Meiboom-Gill (CPMG) sequence
   or a more complicated sequence, set with ``Pulse`` objects.

   .. literalinclude:: tutorials/nv_simple.py
      :language: python
      :lines: 8,9

   The hyperfine couplings are automatically generated at this step assuming point dipole-dipole interactions
   between central spin and bath spins.

4. Compute the coherence function of the qubit using the ``compute`` method of the ``Simulator`` object with
   conventional CCE.

   .. literalinclude:: tutorials/nv_simple.py
      :language: python
      :lines: 11, 12

This function outputs a Numpy array with the same shape as the ``time_points`` and
contains the coherence function computed at each time step.
By default ``compute`` uses the conventional CCE to compute the coherence function.

More detailed examples of using **PyCCE** are available in the tutorials.