Introduction
============

.. ipython:: python
   :suppress:

   import numpy as np
   import gbspy
   np.random.seed(12345)

Some blabla which explains that simulations are handled by the
:py:class:`gbspy.Sim` class, and that quantities are usually passed around as
4D numpy arrays.

Opening a simulation
--------------------

A GBS simulation usually consists in a collection of numerically indexed result
files (``results_00.h5``, ``results_01.h5``, ...), compagnion restart files
(``restart_00.h5``, ``restart_01.h5``, ...), as well as a number of log files.
The files with extension ``.h5`` rely on the
`HDF5 <https://www.hdfgroup.org/solutions/hdf5>`_ storage format.
The user may be familiar with storage conventions (such as
`NetCDF <https://www.unidata.ucar.edu/software/netcdf/>`_ or
`CGNS <http://cgns.github.io/>`_) which also rely on the HDF5 format. The
internal structure of GBS results, however, uses a custom format which will not
be recognized by general purpose packages.

GBSpy provides a mechanism to read *result* files, typically by specifying a
path to a directory containing a series of such files,

.. ipython::
   :verbatim:

   In [1]: import gbspy

   In [2]: path = "/path/to/directory/containing/results"

   In [3]: sim = gbspy.Sim(path)

   In [4]: sim
   Out[4]: <GBS simulation '/path/to/directory/containing/results' (0x14911a610b80)>

It is also possible to open individual result files if needed by passing a path
to the relevant file instead of the simulation directory, as below,

.. ipython::
   :verbatim:

   In [1]: sim = gbspy.Sim("/path/to/directory/containing/results/results_43.h5")

   In [2]: sim
   Out[2]: <GBS simulation '/path/to/directory/containing/results' (0x14911a80fbe0)>

Loading tutorial datasets
-------------------------

If you want to start exploring the functionality of this toolbox but miss a
full simulation, :py:func:`gbspy.tutorial.Sim` allows you to download and open
sample simulations.
An internet connection and about 50MB of disk space will be required for each
sample, as well as having the
`pooch <https://www.fatiando.org/pooch/latest/index.html>`_ package installed.

You can thus start looking around by loading such a dataset, as will be done
throughout this guide, with the snippet below.

.. ipython:: python
   :okwarning:

   import gbspy.tutorial
   sim = gbspy.tutorial.Sim("tcv_neutrals")

   @savefig snowflake_theta.png width=4in
   gbspy.plot2d(sim, "theta")

..
   Data structures
   ---------------

   With the exception of the :py:class:`~gbspy.Sim` class, gbspy does not define
   any particular data structures. Instead, the package relies mostly on
   `Numpy <https://numpy.org/>`_ arrays, `Matplotlib <https://matplotlib.org/>`_
   for data visualization and some `SciPy <https://scipy.org/>`_ functions.
   Familiarity with the basics of each of these packages is expected to help.


   How are physical fields represented? Write a short introduction around
   :py:meth:`~gbspy.Sim.get_field`.

   * 4D arrays, ``(Z,R,phi,t)`` versus the more computational naming
     ``(y,x,z,t)``. Emphasize that most routines in gbspy will expect 4D arrays,
     even when some dimensions can be squeezed. Maybe take some time to define
     the coordinates properly.
   * Arakawa grids, which quantities belong to the density and velocity grids.
     Maybe mention grid switching routines from the :py:mod:`~gbspy.grad` module
     here?
   * How to keep track of coordinates: they're in the simulation object, DIY.
     Probably good to quickly recall how coordinates are normalized (e.g.
     ``x=0.0`` is not :math:`R=0`).